# API Reference: Agent Nodes

## POST `/nodes/admin`

**Summary:** [Admin] Register New Node

**Description:** Admin registers a new Agent Node.
Returns the node record including a generated invite_token that must be
placed in the node's config YAML before deployment.

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `admin_id` | query | Yes | string |  |

#### Request Body

**Required:** Yes

- **Media Type:** `application/json`
- **Schema:** `AgentNodeCreate` (Define in Models)

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'POST' \
  'http://localhost:8000/api/v1/nodes/admin?admin_id=<admin_id>' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

---

## GET `/nodes/admin`

**Summary:** [Admin] List All Nodes

**Description:** Full node list for admin dashboard, including invite_token and skill config.

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `admin_id` | query | Yes | string |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'GET' \
  'http://localhost:8000/api/v1/nodes/admin?admin_id=<admin_id>' \
  -H 'accept: application/json'
```

---

## GET `/nodes/admin/{node_id}`

**Summary:** [Admin] Get Node Detail

**Description:** [Admin] Get Node Detail

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `node_id` | path | Yes | string |  |
| `admin_id` | query | Yes | string |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'GET' \
  'http://localhost:8000/api/v1/nodes/admin/{node_id}?admin_id=<admin_id>' \
  -H 'accept: application/json'
```

---

## PATCH `/nodes/admin/{node_id}`

**Summary:** [Admin] Update Node Config

**Description:** Update display_name, description, skill_config toggles, or is_active.

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `node_id` | path | Yes | string |  |
| `admin_id` | query | Yes | string |  |

#### Request Body

**Required:** Yes

- **Media Type:** `application/json`
- **Schema:** `AgentNodeUpdate` (Define in Models)

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'PATCH' \
  'http://localhost:8000/api/v1/nodes/admin/{node_id}?admin_id=<admin_id>' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

---

## DELETE `/nodes/admin/{node_id}`

**Summary:** [Admin] Deregister Node

**Description:** Delete a node registration and all its access grants.

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `node_id` | path | Yes | string |  |
| `admin_id` | query | Yes | string |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'DELETE' \
  'http://localhost:8000/api/v1/nodes/admin/{node_id}?admin_id=<admin_id>' \
  -H 'accept: application/json'
```

---

## POST `/nodes/admin/{node_id}/access`

**Summary:** [Admin] Grant Group Access

**Description:** Grant a group access to use this node in sessions.

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `node_id` | path | Yes | string |  |
| `admin_id` | query | Yes | string |  |

#### Request Body

**Required:** Yes

- **Media Type:** `application/json`
- **Schema:** `NodeAccessGrant` (Define in Models)

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'POST' \
  'http://localhost:8000/api/v1/nodes/admin/{node_id}/access?admin_id=<admin_id>' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

---

## DELETE `/nodes/admin/{node_id}/access/{group_id}`

**Summary:** [Admin] Revoke Group Access

**Description:** [Admin] Revoke Group Access

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `node_id` | path | Yes | string |  |
| `group_id` | path | Yes | string |  |
| `admin_id` | query | Yes | string |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'DELETE' \
  'http://localhost:8000/api/v1/nodes/admin/{node_id}/access/{group_id}?admin_id=<admin_id>' \
  -H 'accept: application/json'
```

---

## POST `/nodes/admin/mesh/reset`

**Summary:** [Admin] Emergency Mesh Reset

**Description:** DANGEROUS: Clears ALL live node collections from memory and resets DB statuses to offline.
Use this to resolve 'zombie' nodes or flapping connections.

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `admin_id` | query | Yes | string |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'POST' \
  'http://localhost:8000/api/v1/nodes/admin/mesh/reset?admin_id=<admin_id>' \
  -H 'accept: application/json'
```

---

## GET `/nodes/`

**Summary:** List Accessible Nodes

**Description:** Returns nodes the calling user's group has access to.
Merges live connection state from the in-memory registry.

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `user_id` | query | Yes | string |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'GET' \
  'http://localhost:8000/api/v1/nodes/?user_id=<user_id>' \
  -H 'accept: application/json'
```

---

## GET `/nodes/{node_id}/status`

**Summary:** Quick Node Online Check

**Description:** Quick Node Online Check

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `node_id` | path | Yes | string |  |
| `X-User-ID` | header | Yes | string |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'GET' \
  'http://localhost:8000/api/v1/nodes/{node_id}/status' \
  -H 'accept: application/json' \
  -H 'X-User-ID: <your_user_id>'
```

---

## GET `/nodes/{node_id}/terminal`

**Summary:** Read Node Terminal History (AI Use Case)

**Description:** AI-Specific: Returns the most recent 150 terminal interaction chunks for a live node.
This provides context for the AI reasoning agent.

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `node_id` | path | Yes | string |  |
| `X-User-ID` | header | Yes | string |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'GET' \
  'http://localhost:8000/api/v1/nodes/{node_id}/terminal' \
  -H 'accept: application/json' \
  -H 'X-User-ID: <your_user_id>'
```

---

## POST `/nodes/{node_id}/dispatch`

**Summary:** Dispatch Task to Node

**Description:** Queue a shell task to an online node.
Emits task_assigned immediately so the live UI shows it.

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `node_id` | path | Yes | string |  |
| `user_id` | query | Yes | string |  |

#### Request Body

**Required:** Yes

- **Media Type:** `application/json`
- **Schema:** `NodeDispatchRequest` (Define in Models)

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'POST' \
  'http://localhost:8000/api/v1/nodes/{node_id}/dispatch?user_id=<user_id>' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

---

## POST `/nodes/{node_id}/cancel`

**Summary:** Cancel/Interrupt Task on Node

**Description:** Sends a TaskCancelRequest to the specified node.
For shell skills, this typically translates to SIGINT (Ctrl+C).

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `node_id` | path | Yes | string |  |
| `task_id` | query | No | string |  |
| `X-User-ID` | header | Yes | string |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'POST' \
  'http://localhost:8000/api/v1/nodes/{node_id}/cancel?task_id=<task_id>' \
  -H 'accept: application/json' \
  -H 'X-User-ID: <your_user_id>'
```

---

## PATCH `/nodes/preferences`

**Summary:** Update User Node Preferences

**Description:** Save the user's default_node_ids and data_source config into their preferences.
The UI reads this to auto-attach nodes when a new session starts.

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `user_id` | query | Yes | string |  |

#### Request Body

**Required:** No

- **Media Type:** `application/json`
- **Schema:** `UserNodePreferences` (Define in Models)

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'PATCH' \
  'http://localhost:8000/api/v1/nodes/preferences?user_id=<user_id>' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

---

## GET `/nodes/preferences`

**Summary:** Get User Node Preferences

**Description:** Get User Node Preferences

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `user_id` | query | Yes | string |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'GET' \
  'http://localhost:8000/api/v1/nodes/preferences?user_id=<user_id>' \
  -H 'accept: application/json'
```

---

## GET `/nodes/admin/{node_id}/config.yaml`

**Summary:** [Admin] Download Node Config YAML

**Description:** Generate and return the agent_config.yaml content an admin downloads
and places alongside the node client software before deployment.

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `node_id` | path | Yes | string |  |
| `admin_id` | query | Yes | string |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'GET' \
  'http://localhost:8000/api/v1/nodes/admin/{node_id}/config.yaml?admin_id=<admin_id>' \
  -H 'accept: application/json'
```

---

## GET `/nodes/provision/{node_id}`

**Summary:** Headless Provisioning Script (Python)

**Description:** Returns a Python script that can be piped into python3 to automatically
install and start the python-source agent node.

Usage: curl -sSL https://.../provision/{node_id}?token={token} | python3

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `node_id` | path | Yes | string |  |
| `token` | query | Yes | string |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'GET' \
  'http://localhost:8000/api/v1/nodes/provision/{node_id}?token=<token>' \
  -H 'accept: application/json'
```

---

## GET `/nodes/provision/sh/{node_id}`

**Summary:** Headless Provisioning Script (Bash Binary)

**Description:** Returns a Bash script that curls and executes the compiled standalone binary.

Usage: curl -sSL https://.../provision/sh/{node_id}?token={token} | bash

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `node_id` | path | Yes | string |  |
| `token` | query | Yes | string |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'GET' \
  'http://localhost:8000/api/v1/nodes/provision/sh/{node_id}?token=<token>' \
  -H 'accept: application/json'
```

---

## GET `/nodes/provision/binary/{node_id}/{arch}`

**Summary:** Download Self-Contained Binary ZIP Bundle

**Description:** Dynamically zips the specified architecture's cortex-agent binary 
with the autogenerated agent_config.yaml for secure, direct GUI downloads.

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `node_id` | path | Yes | string |  |
| `arch` | path | Yes | string |  |
| `token` | query | Yes | string |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'GET' \
  'http://localhost:8000/api/v1/nodes/provision/binary/{node_id}/{arch}?token=<token>' \
  -H 'accept: application/json'
```

---

## GET `/nodes/provision/binaries/status`

**Summary:** Check binary availability status

**Description:** Check binary availability status

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |

#### Example Usage

```bash
curl -X 'GET' \
  'http://localhost:8000/api/v1/nodes/provision/binaries/status' \
  -H 'accept: application/json'
```

---

## GET `/nodes/admin/{node_id}/download`

**Summary:** [Admin] Download Agent Node Bundle (ZIP)

**Description:** Bundles the entire Agent Node source code along with a pre-configured
agent_config.yaml into a single ZIP file for the user to download.

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `node_id` | path | Yes | string |  |
| `admin_id` | query | Yes | string |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'GET' \
  'http://localhost:8000/api/v1/nodes/admin/{node_id}/download?admin_id=<admin_id>' \
  -H 'accept: application/json'
```

---

## POST `/nodes/validate-token`

**Summary:** [Internal] Validate Node Invite Token

**Description:** Internal HTTP endpoint called by the gRPC SyncConfiguration handler
to validate an invite_token before accepting a node connection.

Returns the node's skill_config (sandbox policy) on success so the
gRPC server can populate the SandboxPolicy response.

Response:
  200 { valid: true, node_id, skill_config, display_name }
  401 { valid: false, reason }

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `token` | query | Yes | string |  |
| `node_id` | query | Yes | string |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'POST' \
  'http://localhost:8000/api/v1/nodes/validate-token?token=<token>&node_id=<node_id>' \
  -H 'accept: application/json'
```

---

## GET `/nodes/{node_id}/fs/ls`

**Summary:** List Directory Content

**Description:** Request a directory listing from a node.
Returns a tree-structured list for the File Navigator.

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `node_id` | path | Yes | string |  |
| `path` | query | No | string |  |
| `session_id` | query | No | string |  |
| `X-User-ID` | header | Yes | string |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'GET' \
  'http://localhost:8000/api/v1/nodes/{node_id}/fs/ls?path=<path>&session_id=<session_id>' \
  -H 'accept: application/json' \
  -H 'X-User-ID: <your_user_id>'
```

---

## GET `/nodes/{node_id}/fs/cat`

**Summary:** Read File Content

**Description:** Read the content of a file on a remote node.

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `node_id` | path | Yes | string |  |
| `path` | query | Yes | string |  |
| `session_id` | query | No | string |  |
| `X-User-ID` | header | Yes | string |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'GET' \
  'http://localhost:8000/api/v1/nodes/{node_id}/fs/cat?path=<path>&session_id=<session_id>' \
  -H 'accept: application/json' \
  -H 'X-User-ID: <your_user_id>'
```

---

## POST `/nodes/{node_id}/fs/touch`

**Summary:** Create File or Directory

**Description:** Create a new file or directory on the node.

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `node_id` | path | Yes | string |  |
| `X-User-ID` | header | Yes | string |  |

#### Request Body

**Required:** Yes

- **Media Type:** `application/json`
- **Schema:** `FileWriteRequest` (Define in Models)

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'POST' \
  'http://localhost:8000/api/v1/nodes/{node_id}/fs/touch' \
  -H 'accept: application/json' \
  -H 'X-User-ID: <your_user_id>' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

---

## GET `/nodes/{node_id}/fs/download`

**Summary:** Download File

**Description:** Download a file from an agent node.
Triggers a fetch to the hub's mirror, then serves it.

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `node_id` | path | Yes | string |  |
| `path` | query | Yes | string |  |
| `session_id` | query | No | string |  |
| `X-User-ID` | header | Yes | string |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'GET' \
  'http://localhost:8000/api/v1/nodes/{node_id}/fs/download?path=<path>&session_id=<session_id>' \
  -H 'accept: application/json' \
  -H 'X-User-ID: <your_user_id>'
```

---

## POST `/nodes/{node_id}/fs/upload`

**Summary:** Upload File

**Description:** Upload a file to an agent node.

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `node_id` | path | Yes | string |  |
| `path` | query | Yes | string |  |
| `session_id` | query | No | string |  |
| `X-User-ID` | header | Yes | string |  |

#### Request Body

**Required:** Yes

- **Media Type:** `multipart/form-data`
- **Schema:** `Body_fs_upload_nodes__node_id__fs_upload_post` (Define in Models)

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'POST' \
  'http://localhost:8000/api/v1/nodes/{node_id}/fs/upload?path=<path>&session_id=<session_id>' \
  -H 'accept: application/json' \
  -H 'X-User-ID: <your_user_id>' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@/path/to/file'
```

---

## POST `/nodes/{node_id}/fs/rm`

**Summary:** Delete File/Directory

**Description:** Delete a file or directory from a remote node.

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `node_id` | path | Yes | string |  |
| `X-User-ID` | header | Yes | string |  |

#### Request Body

**Required:** Yes

- **Media Type:** `application/json`
- **Schema:** `FileDeleteRequest` (Define in Models)

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'POST' \
  'http://localhost:8000/api/v1/nodes/{node_id}/fs/rm' \
  -H 'accept: application/json' \
  -H 'X-User-ID: <your_user_id>' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

---

## POST `/nodes/{node_id}/fs/move`

**Summary:** Move/Rename File or Directory

**Description:** Atomic move/rename within the mesh workspace.

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `node_id` | path | Yes | string |  |
| `X-User-ID` | header | Yes | string |  |

#### Request Body

**Required:** Yes

- **Media Type:** `application/json`
- **Schema:** `FileMoveRequest` (Define in Models)

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'POST' \
  'http://localhost:8000/api/v1/nodes/{node_id}/fs/move' \
  -H 'accept: application/json' \
  -H 'X-User-ID: <your_user_id>' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

---

## POST `/nodes/{node_id}/fs/copy`

**Summary:** Copy File or Directory

**Description:** Atomic copy within the mesh workspace.

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `node_id` | path | Yes | string |  |
| `X-User-ID` | header | Yes | string |  |

#### Request Body

**Required:** Yes

- **Media Type:** `application/json`
- **Schema:** `FileCopyRequest` (Define in Models)

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'POST' \
  'http://localhost:8000/api/v1/nodes/{node_id}/fs/copy' \
  -H 'accept: application/json' \
  -H 'X-User-ID: <your_user_id>' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

---

## GET `/nodes/{node_id}/fs/stat`

**Summary:** Get File Metadata (Stat)

**Description:** Get file metadata directly from the Hub mirror.

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `node_id` | path | Yes | string |  |
| `path` | query | Yes | string |  |
| `session_id` | query | No | string |  |
| `X-User-ID` | header | Yes | string |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'GET' \
  'http://localhost:8000/api/v1/nodes/{node_id}/fs/stat?path=<path>&session_id=<session_id>' \
  -H 'accept: application/json' \
  -H 'X-User-ID: <your_user_id>'
```

---

