Terminal: Session Management

Use these endpoints to list, inspect, attach to, capture, and tear down terminal sessions running inside a Hoody container. The endpoints in this section reach the terminal service through the container-scoped subdomain of the Hoody platform, not the control plane at api.hoody.com. Each session can be inspected through its command history and raw output buffer, driven through a real-time WebSocket, snapshotted as an image, or created and deleted on demand.

All endpoints in this section target https://{projectId}-{containerId}-terminal-1.{server}.containers.hoody.com. Replace {projectId}, {containerId}, and {server} with the identifiers of your container and the Hoody node it runs on. Every request requires an authenticated session token.

Discovery

GET /api/v1/terminal/sessions

Return every terminal session known to the terminal service, including the session’s metadata, recent command history, and the daemon-program metadata when the terminal id is claimed by a hoody-daemon program. Daemon-program terminals have daemon_program: true with a populated daemon object describing the program, no shell, and no command history. Local sessions carry daemon_program: false.

Parameters

Name	In	Type	Required	Description
history_limit	query	integer	No	Max command_history entries to include per session (default: 50, max: 1000)
history_lines	query	integer	No	Alias of history_limit

Response

200

[
  {
    "id": "123",
    "terminal_id": "123",
    "pid": 5678,
    "shell_pid": 5678,
    "created_at": 1698765432,
    "shell": "bash",
    "is_active": true,
    "cols": 120,
    "rows": 40,
    "daemon_program": false,
    "daemon": null,
    "is_ephemeral": false,
    "desktop_mode": true,
    "is_ssh": false,
    "client_count": 1,
    "last_activity": 1698765440,
    "display_id": 7,
    "cwd": "/home/user",
    "initial_cwd": "/home/user",
    "ssh_host": null,
    "ssh_user": null,
    "ssh_port": null,
    "dbus_address": "unix:path=/tmp/dbus-abc,guid=deadbeef",
    "command_history": [
      [1698765432000, "ls -la"],
      [1698765440000, "pwd"]
    ]
  },
  {
    "id": "5000",
    "terminal_id": "5000",
    "pid": 4321,
    "shell_pid": null,
    "created_at": 1698765500,
    "shell": null,
    "is_active": true,
    "cols": 100,
    "rows": 30,
    "daemon_program": true,
    "daemon": {
      "program_id": 12,
      "program_name": "console",
      "user": "root",
      "enabled": true,
      "running": true,
      "connected": true,
      "ended": false
    },
    "is_ephemeral": false,
    "desktop_mode": false,
    "is_ssh": false,
    "client_count": 2,
    "last_activity": 1698765510,
    "display_id": null,
    "cwd": "/opt/console",
    "initial_cwd": null,
    "ssh_host": null,
    "ssh_user": null,
    "ssh_port": null,
    "dbus_address": null,
    "command_history": []
  },
  {
    "id": "5001",
    "terminal_id": "5001",
    "pid": 0,
    "shell_pid": null,
    "created_at": null,
    "shell": null,
    "is_active": false,
    "cols": null,
    "rows": null,
    "daemon_program": true,
    "daemon": {
      "program_id": 13,
      "program_name": "worker",
      "user": "app",
      "enabled": true,
      "running": true,
      "connected": false,
      "ended": false
    },
    "is_ephemeral": false,
    "desktop_mode": false,
    "is_ssh": false,
    "client_count": 0,
    "last_activity": null,
    "display_id": null,
    "cwd": null,
    "initial_cwd": null,
    "ssh_host": null,
    "ssh_user": null,
    "ssh_port": null,
    "dbus_address": null,
    "command_history": []
  }
]

Example request

cURL

curl "https://67e89abc123def456789abcd-890abcdef12345678901cdef-terminal-1.node-example-1.containers.hoody.com/api/v1/terminal/sessions" \
  -H "Authorization: Bearer $HOODY_TOKEN"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://67e89abc123def456789abcd-890abcdef12345678901cdef-terminal-1.node-example-1.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.terminal.sessions.list();

GET /api/v1/terminal/history/{terminal_id}

Retrieve the execution history for a single terminal session, including every command run in that session and its status.

Note

The containers proxy can only inject terminal_id as a query parameter on hostname-routed calls. When calling this endpoint on a terminal-N hostname, the {terminal_id} path segment must always be supplied explicitly, and it must name the host’s terminal: a path id that differs from the query terminal_id (N on a terminal-N host) is refused with 400 TERMINAL_ID_MISMATCH.

Parameters

Name	In	Type	Required	Description
terminal_id	path	string	Yes	Terminal session ID (numeric 1-65535, can also be provided as query parameter). The containers proxy injects only the query form on hostname-routed calls, so this path segment must always be supplied explicitly, and it must name the host’s terminal.

Response

200

{
  "terminal_id": "1",
  "command_count": 2,
  "commands": [
    {
      "command_id": "45678",
      "command": "echo hello",
      "status": "completed",
      "start_time": 1758805971,
      "exit_code": 0,
      "timed_out": false
    }
  ]
}

400

{
  "error": "terminal_id required (in URL path or as query parameter)"
}

Error Code	Title	Description	Resolution
MISSING_TERMINAL_ID	Terminal ID required	Provide terminal_id in path or query	Provide terminal_id in path or query
TERMINAL_ID_MISMATCH	The path terminal_id differs from the query terminal_id, which a terminal-N host sets to N	Send the request to the host of the terminal you name	Send the request to the host of the terminal you name

404

{
  "error": "Terminal session not found"
}

Error Code	Title	Description	Resolution
SESSION_NOT_FOUND	Terminal session does not exist	Check session ID or create new session	Check session ID or create new session

Example request

cURL

curl "https://67e89abc123def456789abcd-890abcdef12345678901cdef-terminal-1.node-example-1.containers.hoody.com/api/v1/terminal/history/1" \
  -H "Authorization: Bearer $HOODY_TOKEN"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://67e89abc123def456789abcd-890abcdef12345678901cdef-terminal-1.node-example-1.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.terminal.commands.list('1');

GET /api/v1/terminal/raw

Retrieve the raw terminal output buffer for a session. The response supports multiple formats via the format query parameter and defaults to a downloadable text file when no format is supplied.

Note

The terminal_id query parameter is optional. On calls routed through a terminal-N containers-proxy hostname, the proxy sets this from the hostname label and overwrites any value you send. 0 (the terminal-0 host) names no terminal to read and is refused with 400 TERMINAL_ID_ZERO.

Parameters

Name	In	Type	Required	Description
terminal_id	query	string	No	Terminal session ID (numeric 1-65535, defaults to "1" if not provided). On calls routed through a terminal-N containers-proxy hostname, the proxy sets this from the hostname label and overwrites any value you send.
format	query	string	No	Output format: download, text, or html (defaults to "download" if not provided).
tail	query	integer	No	Return only the last N lines of output.

Response

200

The response body is the raw terminal output as a downloadable file (application/octet-stream). Clients receive the bytes of the output buffer; on format=html the body is an HTML rendering of the buffer.

400

Error Code	Title	Description	Resolution
TERMINAL_ID_ZERO	terminal_id 0 names no terminal to read	Use the terminal-N host of the terminal you want	Use the terminal-N host of the terminal you want

403

The terminal belongs to a hoody-daemon program and the server is in SSH-only mode, which reaches no local process.

Error Code	Title	Description	Resolution
SSH_ONLY	SSH-only mode: a daemon program’s terminal cannot be reached	SSH-only mode: a daemon program’s terminal cannot be reached	Contact support

404

The terminal session was not found. The response is a plain-text body (text/plain) carrying the not-found message.

409

The terminal id belongs to a hoody-daemon program that cannot be reached: the program is not running, or a local session opened earlier still holds the id.

{
  "error": "terminal 7000 belongs to a daemon program that is not running",
  "code": "DAEMON_PROGRAM_NOT_RUNNING"
}

Error Code	Title	Description	Resolution
DAEMON_PROGRAM_NOT_RUNNING	The daemon program that owns this terminal is not running	Start the program, then retry	Start the program, then retry
DAEMON_TERMINAL	A local session holds a daemon program’s terminal id	DELETE the session to reach the program	DELETE the session to reach the program

Example request

cURL

curl "https://67e89abc123def456789abcd-890abcdef12345678901cdef-terminal-1.node-example-1.containers.hoody.com/api/v1/terminal/raw?terminal_id=1&format=text" \
  -H "Authorization: Bearer $HOODY_TOKEN"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://67e89abc123def456789abcd-890abcdef12345678901cdef-terminal-1.node-example-1.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.terminal.sessions.read({ terminal_id: '1', format: 'text' });

Real-time I/O

GET /api/v1/terminal/ws

Establish a WebSocket connection for real-time bidirectional terminal I/O. Multiple clients can share the same session by using the same terminal_id; a client that omits terminal_id joins the shared terminal 1 unless it asks for ephemeral=true. The protocol uses binary framing where the first byte indicates message type. After the upgrade the client must request the tty subprotocol, then send the JSON_DATA handshake frame (a JSON object starting with {, carrying columns and rows). The server spawns the session’s process only once that frame arrives, so a client that never sends it gets no shell.

Caution

Resizing is WebSocket-only via the RESIZE_TERMINAL frame; there is no REST resize endpoint. Session-creation parameters (shell, cwd, env, cmd, etc.) take effect only when this connection creates the session; joining a session that is already running ignores them. When terminal_id belongs to a hoody-daemon program, the connection attaches to that program’s terminal: session-creation parameters and cmd and pid are ignored.

Parameters

Name	In	Type	Required	Description
terminal_id	query	string	No	Terminal session ID (numeric 1-65535). Omitted, the connection joins the shared terminal 1 that every client without a terminal_id uses; with ephemeral=true it instead gets a fresh id in 40000-65535, reported in the SET_TERMINAL_ID frame. A value that is present but malformed is refused, never mapped to 1. Multiple clients can share by using the same id. On connections routed through a terminal-N containers-proxy hostname, the proxy sets this from the hostname label and overwrites any value you send.
readonly	query	boolean	No	Enable read-only mode for this client (blocks keyboard input). Use true, 1, or no value.
cwd	query	string	No	Working directory for new sessions.
cwd_auto_create	query	boolean	No	Auto-create cwd when the requested working directory does not exist yet. Only applies when cwd is explicitly provided for a new local session. Enable with true, 1, or no value (default: false).
shell	query	string	No	Shell to use (bash, zsh, fish, tmux, ssh, etc.).
user	query	string	No	System user to spawn shell as (requires permissions).
cmd	query	string	No	Base64-encoded command to auto-execute on spawn.
env	query	string	No	Environment variable KEY=VALUE (repeatable).
display	query	string	No	DISPLAY variable for X11 apps (auto-formats :N).
pid	query	integer	No	Attach to existing process PID for monitoring.
ssh_host	query	string	No	SSH server hostname/IP for remote connections.
ssh_user	query	string	No	SSH username (required if ssh_host provided).
ssh_port	query	string	No	SSH port (default: 22).
ssh_password	query	string	No	SSH password (use with caution).
socks5_host	query	string	No	SOCKS5 proxy for SSH.
socks5_port	query	string	No	SOCKS5 port (default: 1080).
socks5_user	query	string	No	SOCKS5 proxy username (alphanumeric with _-. characters).
socks5_pass	query	string	No	SOCKS5 proxy password (shell-dangerous characters are refused).
ssh_key	query	string	No	Base64-encoded SSH private key for key authentication (alternative to ssh_password).
display_id	query	string	No	Alias of display; when both are sent, display wins.
ephemeral	query	boolean	No	Throwaway session: without a terminal_id a fresh id in 40000-65535 is allocated instead of joining shared terminal 1; the display environment is not inherited, a cmd= command exits the shell when it finishes, and the idle session is cleaned up. Accepts true, 1, or yes (default: false). Ignored with agent=true.
reset	query	boolean	No	Tear down the session’s running process (or SSH / PID attachment) and start a fresh one before this client joins. Accepts true, 1, or a bare flag (default: false).
startup_script	query	string	No	Absolute path of a script to run before the shell starts; relative paths and paths containing .. are ignored. Ignored with agent=true.
env_inject	query	boolean	No	Inject the HOODY_* environment variables into the spawned shell (default: true; only false or 0 disables it).
desktop	query	boolean	No	Desktop mode: sets TTYD_DESKTOP_MODE=true in the shell environment (default: false). Ignored with agent=true.
desktop_env	query	string	No	Desktop environment for desktop mode; implies desktop=true. Allowed values: xfce, mate. Other values are ignored. Not started again when a window manager already runs on the display; it keeps running after the session is deleted (POST /api/v1/system/displays/{display}/stop ends it).
debug	query	boolean	No	Sets TTYD_DEBUG=true in the shell environment (default: false).
welcome	query	boolean	No	Show the Hoody welcome banner when the shell starts (default: false).
agent	query	boolean	No	Launch the server-configured Hoody Agent TUI instead of a shell. A locked-down mode: shell, cmd, user, ssh_*, pid, startup_script, desktop, and ephemeral are ignored (default: false).
onboarding	query	boolean	No	With agent=true, start the agent’s first-run onboarding (default: false).
arg	query	string	No	Command-line argument for the shell, repeatable and kept in order. Accepted only when URL arguments are enabled on this server; ignored otherwise.

Response

101

Switching Protocols

The WebSocket upgrade succeeded. The body content type is text/plain and carries the literal Switching Protocols text shown above.

400

{
  "error": "Invalid terminal_id format"
}

Error Code	Title	Description	Resolution
INVALID_TERMINAL_ID	Terminal ID must be numeric 1-65535	Provide valid terminal_id	Provide valid terminal_id
INVALID_PARAMETERS	Invalid URL parameters	Check parameter format	Check parameter format

403

{
  "error": "Maximum clients reached"
}

Error Code	Title	Description	Resolution
MAX_CLIENTS_REACHED	Server at capacity	Try again later	Try again later
ORIGIN_CHECK_FAILED	Origin validation failed	Connect from allowed origin	Connect from allowed origin

503

{
  "error": "Service temporarily unavailable"
}

Example request

cURL

curl "https://67e89abc123def456789abcd-890abcdef12345678901cdef-terminal-1.node-example-1.containers.hoody.com/api/v1/terminal/ws?terminal_id=1&shell=bash" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Upgrade: websocket" \
  -H "Connection: Upgrade" \
  -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" \
  -H "Sec-WebSocket-Version: 13" \
  -H "Sec-WebSocket-Protocol: tty"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://67e89abc123def456789abcd-890abcdef12345678901cdef-terminal-1.node-example-1.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.terminal.sessions.connect({ terminal_id: '1', shell: 'bash' });

Snapshots

GET /api/v1/terminal/screenshot

Render the terminal’s ANSI output buffer to an image. Screenshots are automatically saved to /hoody/storage/hoody-terminal/screenshots/{terminal_id}/ with a timestamp as the filename. The save query parameter controls whether the image is also persisted to that directory.

Note

The terminal_id query parameter is required on this endpoint because the proxy cannot fill it for non-hostname-routed calls. On a terminal-N hostname the proxy sets it from the label and overwrites any value supplied. Always send it explicitly when calling the terminal service without the proxy.

Parameters

Name	In	Type	Required	Description
terminal_id	query	string	Yes	Terminal session ID (numeric 1-65535). On calls routed through a terminal-N containers-proxy hostname, the proxy sets this from the hostname label and overwrites any value you send, so pick the terminal via the hostname and supply this directly only when calling the terminal service without the proxy.
format	query	string	No	Output format: png, jpeg, gif (default: png).
foreground	query	string	No	Foreground color: black, red, green, yellow, blue, magenta, cyan, white, or RGB R,G,B,A (default: white).
background	query	string	No	Background color: same as foreground options (default: black).
fontsize	query	integer	No	Font size in pixels (default: 20).
save	query	boolean	No	Save to storage directory (default: true).

Response

200

The response body is the rendered screenshot image (image/gif). The response also carries an X-Screenshot-Path header pointing to the saved file when persistence is enabled.

403

The terminal belongs to a hoody-daemon program and the server is in SSH-only mode, which reaches no local process.

Error Code	Title	Description	Resolution
SSH_ONLY	SSH-only mode: a daemon program’s terminal cannot be reached	SSH-only mode: a daemon program’s terminal cannot be reached	Contact support

409

The terminal id belongs to a hoody-daemon program that cannot be reached: the program is not running, or a local session opened earlier still holds the id.

{
  "error": "terminal 7000 belongs to a daemon program that is not running",
  "code": "DAEMON_PROGRAM_NOT_RUNNING"
}

Error Code	Title	Description	Resolution
DAEMON_PROGRAM_NOT_RUNNING	The daemon program that owns this terminal is not running	Start the program, then retry	Start the program, then retry
DAEMON_TERMINAL	A local session holds a daemon program’s terminal id	DELETE the session to reach the program	DELETE the session to reach the program

500

{
  "error": "Screenshot tool not available or execution failed"
}

Error Code	Title	Description	Resolution
TOOL_NOT_AVAILABLE	Screenshot tool (textimg) not installed	Install with go install github.com/jiro4989/textimg@latest	Install with go install github.com/jiro4989/textimg@latest

Example request

cURL

curl "https://67e89abc123def456789abcd-890abcdef12345678901cdef-terminal-1.node-example-1.containers.hoody.com/api/v1/terminal/screenshot?terminal_id=1&format=png&fontsize=18" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  --output screenshot.png

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://67e89abc123def456789abcd-890abcdef12345678901cdef-terminal-1.node-example-1.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.terminal.sessions.captureScreenshot({ terminal_id: '1', format: 'png', fontsize: 18 });

Session lifecycle

POST /api/v1/terminal/create

Create a new terminal session, or return success if a session with the same terminal_id already exists (the running session keeps its original configuration). A running ephemeral session is not returned for a request that does not ask for one; that response is a 409 EPHEMERAL_SESSION. When a Hoody Display is configured, the endpoint blocks until the display server is accepting connections by default, so the caller can immediately use the display after the response.

This endpoint takes no URL parameters.

Request Body

Name	Type	Required	Description
terminal_id	string	No	Terminal session ID (numeric 1-65535). Required unless ephemeral is true, in which case it is auto-generated (range 40000-65535). On a terminal-N host, the proxy sets the query terminal_id to N; a body terminal_id that differs from it is refused with 400 TERMINAL_ID_MISMATCH.
ephemeral	boolean	No	Auto-generate terminal ID and enable ephemeral session mode. Ephemeral sessions auto-clean after idle timeout and strip DISPLAY environment (default: false).
display	string	No	X11 display number (for example "1" or ":1"). Sets the DISPLAY env var and enables Hoody Display readiness waiting. The display is started if it is not running and reused if it is; it keeps running after the session is deleted (stop it with POST /api/v1/system/displays/{display}/stop).
shell	string	No	Shell to use (bash, zsh, fish, sh). Ignored for SSH sessions.
user	string	No	System user to spawn the shell as. Ignored for SSH sessions.
cwd	string	No	Working directory for the terminal. Ignored for SSH sessions.
startup_script	string	No	Path to startup script to run.
welcome	boolean	No	Show welcome message on startup (default: false).
debug	boolean	No	Enable debug output in wrapper script (default: false).
desktop	boolean	No	Enable Hoody Display desktop mode. Provides a full desktop environment instead of seamless individual windows (default: false).
desktop_env	string	No	Desktop environment to launch (implies desktop=true). Valid values: xfce, mate. Not started again when a window manager already runs on the display. It belongs to the display and keeps running after the session is deleted.
cols	integer	No	Terminal columns (default: 80).
rows	integer	No	Terminal rows (default: 24).
wait_until_display	boolean	No	Whether to wait for Hoody Display readiness (default: true when display is configured).
wait_timeout	integer	No	Timeout in seconds for waiting (default: 300).
ssh_host	string	No	SSH hostname/IP. Required together with ssh_user for SSH sessions.
ssh_user	string	No	SSH username. Required together with ssh_host for SSH sessions.
ssh_port	string	No	SSH port (default: 22).
ssh_password	string	No	SSH password. Cannot contain shell-dangerous characters.
ssh_key	string	No	Base64-encoded SSH private key (PEM format).
socks5_host	string	No	SOCKS5 proxy hostname/IP for routing SSH connections.
socks5_port	string	No	SOCKS5 proxy port (default: 1080).
socks5_user	string	No	SOCKS5 proxy authentication username.
socks5_pass	string	No	SOCKS5 proxy authentication password.

Response

200

{
  "status": "ok",
  "terminal_id": "1",
  "pid": 12345,
  "display_ready": true,
  "message": "Terminal session created"
}

400

{
  "error": "Missing 'terminal_id' field"
}

Error Code	Title	Description	Resolution
MISSING_TERMINAL_ID	terminal_id field is required	terminal_id field is required	Contact support
INVALID_TERMINAL_ID	Terminal ID must be numeric 1-65535	Terminal ID must be numeric 1-65535	Contact support
TERMINAL_ID_MISMATCH	The body terminal_id differs from the query terminal_id, which a terminal-N host sets to N	Send the request to the host of the terminal you name, or leave terminal_id out of the body	Send the request to the host of the terminal you name, or leave terminal_id out of the body

403

{
  "error": "mkdir(/restricted/path) failed: Permission denied"
}

Error Code	Title	Description	Resolution
CWD_PERMISSION_DENIED	Requested working directory could not be created	Choose a writable path or disable cwd_auto_create	Choose a writable path or disable cwd_auto_create

405

A request method other than POST was used. The response includes an Allow: POST header and a Connection: close header.

{
  "error": "method_not_allowed",
  "allow": "POST"
}

409

The terminal id belongs to a hoody-daemon program (whose terminal runs the program, not a shell, so no shell is started there), or the id names a running ephemeral session and the request did not ask for one.

{
  "error": "terminal 7000 belongs to a daemon program and has no shell; drive it with snapshot/press/paste/write/wait or attach over WebSocket",
  "code": "DAEMON_TERMINAL"
}

Error Code	Title	Description	Resolution
DAEMON_TERMINAL	Terminal belongs to a daemon program	Drive or attach to the program instead of starting a shell on its terminal id	Drive or attach to the program instead of starting a shell on its terminal id
EPHEMERAL_SESSION	The terminal id names a running ephemeral session	An execute with ephemeral=true made it or turned it ephemeral; it has no display and is cleaned up when idle. Delete it (DELETE /api/v1/terminal/{terminal_id}) and create it again, or use another terminal id	Delete it and create it again, or use another terminal id

500

{
  "error": "Failed to spawn process"
}

Error Code	Title	Description	Resolution
SPAWN_FAILED	Failed to create terminal process	Failed to create terminal process	Contact support

Example request

cURL

curl -X POST "https://67e89abc123def456789abcd-890abcdef12345678901cdef-terminal-1.node-example-1.containers.hoody.com/api/v1/terminal/create" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "terminal_id": "1",
    "shell": "bash",
    "cwd": "/home/user",
    "cols": 120,
    "rows": 40
  }'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://67e89abc123def456789abcd-890abcdef12345678901cdef-terminal-1.node-example-1.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.terminal.sessions.create({
  terminal_id: '1',
  shell: 'bash',
  cwd: '/home/user',
  cols: 120,
  rows: 40
});

DELETE /api/v1/terminal/{terminal_id}

Completely destroy and remove a terminal session. The call kills the session’s processes, frees its resources, and removes the session from memory. Attached WebSocket clients are closed with code 4410 and reason session deleted, a code the SDK and the web client do not reconnect on by themselves; an attach creates the session it names, so a reconnect would start a fresh shell under the deleted id. A display the session started (its display and any desktop environment) is not part of the session and keeps running. Stop it with POST /api/v1/system/displays/{display}/stop.

Note

The containers proxy cannot fill the {terminal_id} path segment. Supply it explicitly even on hostname-routed calls, and it must name the host’s terminal: a path id that differs from the query terminal_id (N on a terminal-N host) is refused with 400 TERMINAL_ID_MISMATCH.

Parameters

Name	In	Type	Required	Description
terminal_id	path	string	Yes	Terminal session ID to delete (numeric 1-65535). The containers proxy cannot fill this path segment, so supply it explicitly even on hostname-routed calls, and it must name the host’s terminal.

Response

200

{
  "message": "Terminal session deleted",
  "terminal_id": "1"
}

400

Error Code	Title	Description	Resolution
TERMINAL_ID_MISMATCH	The path terminal_id differs from the query terminal_id, which a terminal-N host sets to N	Send the request to the host of the terminal you name	Send the request to the host of the terminal you name

404

{
  "error": "Terminal session not found"
}

Error Code	Title	Description	Resolution
SESSION_NOT_FOUND	Terminal session does not exist	Verify terminal ID	Verify terminal ID

Example request

cURL

curl -X DELETE "https://67e89abc123def456789abcd-890abcdef12345678901cdef-terminal-1.node-example-1.containers.hoody.com/api/v1/terminal/1" \
  -H "Authorization: Bearer $HOODY_TOKEN"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://67e89abc123def456789abcd-890abcdef12345678901cdef-terminal-1.node-example-1.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.terminal.sessions.delete('1');