API Reference

All API endpoints (except /health) require authentication when auth.secret is configured. The server accepts both Authorization: Bearer <token> and Authorization: Basic <base64> headers. All request and response bodies use JSON with camelCase field names.

Health check

`GET /health`

No authentication required.

Response:

{
  "status": "ok",
  "apiPort": 8080
}

Repositories

`POST /api/list-repos`

List all repositories managed by NomadFlowCode.

Request body: none (empty or {})

Response:

{
  "repos": [
    {
      "name": "my-project",
      "path": "/home/user/.nomadflowcode/repos/my-project",
      "branch": "main"
    }
  ]
}

`POST /api/clone-repo`

Clone a git repository into NomadFlowCode's managed directory.

Request body:

{
  "url": "https://github.com/user/repo.git",
  "token": "ghp_xxxx",
  "name": "custom-name"
}

Field	Type	Required	Description
`url`	string	yes	Git clone URL
`token`	string	no	Git credential token (inserted into the URL for HTTPS clones)
`name`	string	no	Custom name for the repository directory

Response:

{
  "name": "repo",
  "path": "/home/user/.nomadflowcode/repos/repo",
  "branch": "main"
}

Features

`POST /api/list-features`

List all features (worktrees) for a repository.

Request body:

{
  "repoPath": "/home/user/.nomadflowcode/repos/my-project"
}

Response:

{
  "features": [
    {
      "name": "feature-a",
      "worktreePath": "/home/user/.nomadflowcode/worktrees/my-project/feature-a",
      "branch": "feature/feature-a",
      "isActive": true,
      "isMain": false
    }
  ]
}

Field	Type	Description
`name`	string	Feature name
`worktreePath`	string	Absolute path to the worktree directory
`branch`	string	Git branch name
`isActive`	boolean	Whether this feature's terminal session is currently selected
`isMain`	boolean	Whether this is the main/default branch

`POST /api/create-feature`

Create a new feature branch with its own worktree and terminal session.

Request body:

{
  "repoPath": "/home/user/.nomadflowcode/repos/my-project",
  "branchName": "my-feature",
  "baseBranch": "main"
}

Field	Type	Required	Default	Description
`repoPath`	string	yes	—	Path to the repository
`branchName`	string	yes	—	Name for the new feature branch
`baseBranch`	string	no	`"main"`	Branch to base the feature on

Response:

{
  "worktreePath": "/home/user/.nomadflowcode/worktrees/my-project/my-feature",
  "branch": "feature/my-feature"
}

`POST /api/switch-feature`

Switch to an existing feature's terminal session.

Request body:

{
  "repoPath": "/home/user/.nomadflowcode/repos/my-project",
  "featureName": "my-feature"
}

Response:

{
  "switched": true,
  "worktreePath": "/home/user/.nomadflowcode/worktrees/my-project/my-feature",
  "worktreeName": "my-feature"
}

Field	Type	Description
`switched`	boolean	Whether the switch was successful
`worktreePath`	string	Path to the worktree
`worktreeName`	string	Name of the worktree

`POST /api/delete-feature`

Delete a feature branch and its worktree.

Request body:

{
  "repoPath": "/home/user/.nomadflowcode/repos/my-project",
  "featureName": "my-feature"
}

Response:

{
  "deleted": true
}

`POST /api/list-branches`

List all branches for a repository.

Request body:

{
  "repoPath": "/home/user/.nomadflowcode/repos/my-project"
}

Response:

{
  "branches": ["main", "develop", "feature/login"],
  "defaultBranch": "main"
}

`POST /api/attach-branch`

Attach to an existing branch by creating a worktree for it.

Request body:

{
  "repoPath": "/home/user/.nomadflowcode/repos/my-project",
  "branchName": "feature/login"
}

Response:

{
  "worktreePath": "/home/user/.nomadflowcode/worktrees/my-project/login",
  "branch": "feature/login",
  "worktreeName": "login"
}

Sessions

`POST /api/list-sessions`

List all active PTY sessions.

Request body: none (empty or {})

Response:

{
  "sessions": [
    {
      "id": "abc123",
      "worktreePath": "/home/user/.nomadflowcode/worktrees/my-project/my-feature",
      "agentType": "shell"
    }
  ]
}

`POST /api/create-session`

Create a new PTY session in a worktree.

Request body:

{
  "worktreePath": "/home/user/.nomadflowcode/worktrees/my-project/my-feature",
  "agentType": "shell"
}

Field	Type	Required	Description
`worktreePath`	string	yes	Path to the worktree directory
`agentType`	string	no	Type of agent session (default: `"shell"`)

Response:

{
  "session": {
    "id": "abc123",
    "worktreePath": "/home/user/.nomadflowcode/worktrees/my-project/my-feature",
    "agentType": "shell"
  }
}

`POST /api/select-session`

Select an active session as the current session.

Request body:

{
  "sessionId": "abc123"
}

Response:

{
  "selected": true
}

`POST /api/close-session`

Close an active PTY session.

Request body:

{
  "sessionId": "abc123"
}

Response:

{
  "closed": true
}

File operations

`POST /api/worktree-status`

Get the git status of a worktree (modified, added, deleted files).

Request body:

{
  "worktreePath": "/home/user/.nomadflowcode/worktrees/my-project/my-feature"
}

Response:

{
  "status": [
    { "path": "src/main.rs", "status": "modified" },
    { "path": "src/new.rs", "status": "added" }
  ]
}

`POST /api/file-diff`

Get the git diff for a specific file in a worktree.

Request body:

{
  "worktreePath": "/home/user/.nomadflowcode/worktrees/my-project/my-feature",
  "filePath": "src/main.rs"
}

Response:

{
  "diff": "--- a/src/main.rs\n+++ b/src/main.rs\n@@ -1,3 +1,4 @@\n..."
}

`POST /api/file-content`

Read the content of a file in a worktree.

Request body:

{
  "worktreePath": "/home/user/.nomadflowcode/worktrees/my-project/my-feature",
  "filePath": "src/main.rs"
}

Response:

{
  "filePath": "src/main.rs",
  "content": "fn main() {\n    println!(\"Hello\");\n}\n"
}

`POST /api/list-dir`

List the contents of a directory in a worktree.

Request body:

{
  "worktreePath": "/home/user/.nomadflowcode/worktrees/my-project/my-feature",
  "relativePath": "src"
}

Response:

{
  "files": ["main.rs", "lib.rs"],
  "directories": ["models", "services"]
}

Panes

`POST /api/list-panes`

List all active PTY panes.

Request body: none (empty or {})

Response:

{
  "panes": [
    {
      "id": 1,
      "repo": "my-project",
      "worktree": "my-feature"
    }
  ]
}

`POST /api/destroy-pane`

Destroy an active PTY pane.

Request body:

{
  "paneId": 1
}

Response:

{
  "destroyed": true
}

Terminal WebSocket

`GET /ws/panes`

The central WebSocket endpoint for all terminal communication. Supports multiplexing multiple panes over a single connection.

Authentication:

Method	Description
Query parameter	`?token=<secret>`
Subprotocol header	`Sec-WebSocket-Protocol: bearer.<secret>`

The subprotocol method is preferred as it avoids exposing the secret in URLs/logs. When using the subprotocol, the server echoes back the protocol in its response header to complete the handshake.

Example (query parameter):

ws://your-server:8080/ws/panes?token=your-secret

Example (subprotocol):

GET /ws/panes HTTP/1.1
Sec-WebSocket-Protocol: bearer.your-secret

Protocol: Binary framing with custom multiplexing. Supports control messages (create, destroy, subscribe) and raw PTY data.

On this page