Terminal API

List terminal sessions

GET /api/v1/terminal/sessions

const { data: sessions } = await puchify.terminal.listSessions()

sessions = puchify.terminal.list_sessions()

sessions, err := client.Terminal.ListSessions(ctx)

puchify terminal sessions list

curl https://api.puchify.com/api/v1/terminal/sessions \
  -H "Authorization: Bearer $PUCHIFY_API_KEY"

Query parameters:

Parameter	Type	Description
`status`	string	Filter by status (`active`, `closed`, `timeout`)
`cursor`	string	Pagination cursor
`limit`	integer (1-100)	Results per page (default 50)

Create a terminal session

POST /api/v1/terminal/sessions

const { data: session } = await puchify.terminal.createSession({
  server_id: "svr_abc123",
})

session = puchify.terminal.create_session(server_id="svr_abc123")

session, err := client.Terminal.CreateSession(ctx, &puchify.CreateTerminalInput{
  ServerID: "svr_abc123",
})

puchify terminal session create --server-id svr_abc123

curl -X POST https://api.puchify.com/api/v1/terminal/sessions \
  -H "Authorization: Bearer $PUCHIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"server_id":"svr_abc123"}'

Request body:

Field	Type	Required	Description
`server_id`	string	yes	Server ID to connect to
`width`	integer	no	Initial terminal width in columns (default: 80)
`height`	integer	no	Initial terminal height in rows (default: 24)

Returns a session ID and WebSocket URL for the interactive terminal stream.

Get a terminal session

GET /api/v1/terminal/sessions/{id}

const { data: session } = await puchify.terminal.getSession("term_abc123")

session = puchify.terminal.get_session("term_abc123")

session, err := client.Terminal.GetSession(ctx, "term_abc123")

puchify terminal session get term_abc123

curl https://api.puchify.com/api/v1/terminal/sessions/term_abc123 \
  -H "Authorization: Bearer $PUCHIFY_API_KEY"

Close a terminal session

DELETE /api/v1/terminal/sessions/{id}

await puchify.terminal.closeSession("term_abc123")

puchify.terminal.close_session("term_abc123")

err := client.Terminal.CloseSession(ctx, "term_abc123")

puchify terminal session close term_abc123

curl -X DELETE https://api.puchify.com/api/v1/terminal/sessions/term_abc123 \
  -H "Authorization: Bearer $PUCHIFY_API_KEY"

WebSocket stream

Connect to the WebSocket endpoint to send and receive terminal I/O:

ws://api.puchify.com/api/v1/terminal/sessions/{id}/stream

const ws = new WebSocket(
  `wss://api.puchify.com/api/v1/terminal/sessions/${sessionId}/stream`
)
ws.onopen = () => ws.send(JSON.stringify({ type: "input", data: "ls -la\n" }))
ws.onmessage = (event) => {
  const msg = JSON.parse(event.data)
  if (msg.type === "output") process.stdout.write(msg.data)
}

import websockets, asyncio, json
async def terminal():
    async with websockets.connect(
        f"wss://api.puchify.com/api/v1/terminal/sessions/{session_id}/stream"
    ) as ws:
        await ws.send(json.dumps({"type": "input", "data": "ls -la\n"}))
        async for msg in ws:
            data = json.loads(msg)
            if data["type"] == "output":
                print(data["data"], end="")

puchify terminal session connect term_abc123

WebSocket message types:

Direction	Type	Payload	Description
Client → Server	`input`	`{ "data": "command\n" }`	Send terminal input
Client → Server	`resize`	`{ "cols": 120, "rows": 40 }`	Resize terminal window
Server → Client	`output`	`{ "data": "output text" }`	Terminal output
Server → Client	`exit`	`{ "code": 0 }`	Session ended with exit code

The terminal session automatically closes after 15 minutes of inactivity.

Response shape

{
  "data": {
    "id": "term_abc123",
    "server_id": "svr_abc123",
    "status": "active",           // active | closed | timeout
    "width": 80,
    "height": 24,
    "websocket_url": "wss://api.puchify.com/api/v1/terminal/sessions/term_abc123/stream",
    "created_at": "2026-05-28T10:30:00Z",
    "closed_at": null
  },
  "meta": {
    "persistence": "synced"
  }
}

Error codes

Code	Description
`404`	Server or session not found
`409`	Server is not running; cannot open terminal