Sessions - HAPI

GET /api/sessions

List all sessions in the authenticated user’s namespace. Authentication: Required

Response

sessions

array

Array of session summaries, sorted by active status and updated time.

Show Session summary properties

string

Session ID

namespace

string

Namespace this session belongs to

active

boolean

Whether the session is currently active

activeAt

number

Unix timestamp (ms) when session became active

createdAt

number

Unix timestamp (ms) when session was created

updatedAt

number

Unix timestamp (ms) when session was last updated

thinking

boolean

Whether the agent is currently thinking

metadata

object

Session metadata (path, host, name, etc.)

agentState

object

Agent state including pending requests

permissionMode

string

Current permission mode (e.g., “default”, “bypassPermissions”)

modelMode

string

Current model mode (e.g., “default”, “sonnet”, “opus”)

Example

curl -H "Authorization: Bearer <token>" \
  http://127.0.0.1:3006/api/sessions

{
  "sessions": [
    {
      "id": "abc123",
      "namespace": "default",
      "active": true,
      "activeAt": 1709856000000,
      "createdAt": 1709850000000,
      "updatedAt": 1709856000000,
      "thinking": false,
      "metadata": {
        "path": "/home/user/project",
        "host": "laptop",
        "name": "My Project",
        "flavor": "claude"
      },
      "permissionMode": "default"
    }
  ]
}

GET /api/sessions/:id

Get full details for a specific session. Authentication: Required

Path Parameters

string

required

Session ID

Response

session

object

Full session object with all metadata and state

Example

curl -H "Authorization: Bearer <token>" \
  http://127.0.0.1:3006/api/sessions/abc123

Errors

403 - Access denied (session belongs to different namespace)
404 - Session not found
503 - Hub not connected

POST /api/sessions/:id/abort

Abort a running session. Authentication: Required

Path Parameters

string

required

Session ID

Response

{"ok": true}

Example

curl -X POST -H "Authorization: Bearer <token>" \
  http://127.0.0.1:3006/api/sessions/abc123/abort

Errors

403 - Access denied
404 - Session not found
409 - Session not active

POST /api/sessions/:id/switch

Switch an active session to remote mode (web-controlled). Authentication: Required

Path Parameters

string

required

Session ID

Response

{"ok": true}

Example

curl -X POST -H "Authorization: Bearer <token>" \
  http://127.0.0.1:3006/api/sessions/abc123/switch

Errors

403 - Access denied
404 - Session not found
409 - Session not active

POST /api/sessions/:id/resume

Resume an inactive session on an available machine. Authentication: Required

Path Parameters

string

required

Session ID

Response

type

string

“success”

sessionId

string

The resumed session ID

Example

curl -X POST -H "Authorization: Bearer <token>" \
  http://127.0.0.1:3006/api/sessions/abc123/resume

{
  "type": "success",
  "sessionId": "abc123"
}

Errors

403 - Access denied
404 - Session not found
503 - No machine online

POST /api/sessions/:id/upload

Upload a file to an active session (max 50MB). Authentication: Required

Path Parameters

string

required

Session ID

Request Body

filename

string

required

Filename (max 255 chars)

content

string

required

Base64-encoded file content

mimeType

string

required

MIME type (max 255 chars)

Response

success

boolean

Whether upload succeeded

path

string

Path where file was saved

error

string

Error message if failed

Example

curl -X POST -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "screenshot.png",
    "content": "iVBORw0KGgoAAAANS...",
    "mimeType": "image/png"
  }' \
  http://127.0.0.1:3006/api/sessions/abc123/upload

{
  "success": true,
  "path": "/tmp/hapi-upload-abc123-screenshot.png"
}

Errors

400 - Invalid body
403 - Access denied
404 - Session not found
409 - Session not active
413 - File too large (max 50MB)
500 - Upload failed

POST /api/sessions/:id/upload/delete

Delete a previously uploaded file. Authentication: Required

Path Parameters

string

required

Session ID

Request Body

path

string

required

Path to the uploaded file

Response

success

boolean

Whether deletion succeeded

Example

curl -X POST -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"path": "/tmp/hapi-upload-abc123-screenshot.png"}' \
  http://127.0.0.1:3006/api/sessions/abc123/upload/delete

POST /api/sessions/:id/archive

Archive an active session. Authentication: Required

Response

{"ok": true}

Example

curl -X POST -H "Authorization: Bearer <token>" \
  http://127.0.0.1:3006/api/sessions/abc123/archive

PATCH /api/sessions/:id

Rename a session. Authentication: Required

Request Body

name

string

required

New session name (1-255 chars)

Response

{"ok": true}

Example

curl -X PATCH -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Project Name"}' \
  http://127.0.0.1:3006/api/sessions/abc123

Errors

400 - Invalid body
409 - Version conflict (session modified concurrently)
500 - Failed to rename

DELETE /api/sessions/:id

Delete an inactive session. Authentication: Required

Response

{"ok": true}

Example

curl -X DELETE -H "Authorization: Bearer <token>" \
  http://127.0.0.1:3006/api/sessions/abc123

Errors

409 - Cannot delete active session (archive first)

GET /api/sessions/:id/slash-commands

List available slash commands for a session. Authentication: Required

Response

success

boolean

Whether the request succeeded

commands

array

Array of slash command names

Example

curl -H "Authorization: Bearer <token>" \
  http://127.0.0.1:3006/api/sessions/abc123/slash-commands

{
  "success": true,
  "commands": ["/commit", "/push", "/test"]
}

GET /api/sessions/:id/skills

List available skills for a session. Authentication: Required

Response

success

boolean

Whether the request succeeded

skills

array

Array of skill objects

Example

curl -H "Authorization: Bearer <token>" \
  http://127.0.0.1:3006/api/sessions/abc123/skills

POST /api/sessions/:id/permission-mode

Set the permission mode for an active session. Authentication: Required

Request Body

mode

string

required

Permission mode. Valid values depend on agent flavor:

Claude: default, acceptEdits, bypassPermissions, plan
Codex/Gemini: default, read-only, safe-yolo, yolo
OpenCode: default, yolo
Cursor: default, plan, ask, yolo

Response

{"ok": true}

Example

curl -X POST -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"mode": "bypassPermissions"}' \
  http://127.0.0.1:3006/api/sessions/abc123/permission-mode

Errors

400 - Invalid permission mode for session flavor
409 - Failed to apply mode

POST /api/sessions/:id/model

Set the model mode for an active Claude session. Authentication: Required

Request Body

model

string

required

Model mode: default, sonnet, or opus (Claude only)

Response

{"ok": true}

Example

curl -X POST -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"model": "opus"}' \
  http://127.0.0.1:3006/api/sessions/abc123/model

Errors

400 - Model mode only supported for Claude sessions
409 - Failed to apply mode

Overview

REST API

WebSocket API

Server-Sent Events

​GET /api/sessions

​Response

​Example

​GET /api/sessions/:id

​Path Parameters

​Response

​Example

​Errors

​POST /api/sessions/:id/abort

​Path Parameters

​Response

​Example

​Errors

​POST /api/sessions/:id/switch

​Path Parameters

​Response

​Example

​Errors

​POST /api/sessions/:id/resume

​Path Parameters

​Response

​Example

​Errors

​POST /api/sessions/:id/upload

​Path Parameters

​Request Body

​Response

​Example

​Errors

​POST /api/sessions/:id/upload/delete

​Path Parameters

​Request Body

​Response

​Example

​POST /api/sessions/:id/archive

​Response

​Example

​PATCH /api/sessions/:id

​Request Body

​Response

​Example

​Errors

​DELETE /api/sessions/:id

​Response

​Example

​Errors

​GET /api/sessions/:id/slash-commands

​Response

​Example

​GET /api/sessions/:id/skills

​Response

​Example

​POST /api/sessions/:id/permission-mode

​Request Body

​Response

​Example

​Errors

​POST /api/sessions/:id/model

​Request Body

​Response

​Example

​Errors

Build docs developers (and LLMs) love

GET /api/sessions

Response

Example

GET /api/sessions/:id

Path Parameters

Response

Example

Errors

POST /api/sessions/:id/abort

Path Parameters

Response

Example

Errors

POST /api/sessions/:id/switch

Path Parameters

Response

Example

Errors

POST /api/sessions/:id/resume

Path Parameters

Response

Example

Errors

POST /api/sessions/:id/upload

Path Parameters

Request Body

Response

Example

Errors

POST /api/sessions/:id/upload/delete

Path Parameters

Request Body

Response

Example

POST /api/sessions/:id/archive

Response

Example

PATCH /api/sessions/:id

Request Body

Response

Example

Errors

DELETE /api/sessions/:id

Response

Example

Errors

GET /api/sessions/:id/slash-commands

Response

Example

GET /api/sessions/:id/skills

Response

Example

POST /api/sessions/:id/permission-mode

Request Body

Response

Example

Errors

POST /api/sessions/:id/model

Request Body

Response

Example

Errors