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

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

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

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

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

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

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
`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

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

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

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

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

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

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
`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

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: Yes

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

Responses

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

Example Usage

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

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

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

Description: Returns a Python script that can be piped into python3 to automatically install and start the 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

curl -X 'GET' \
  'http://localhost:8000/api/v1/nodes/provision/{node_id}?token=<token>' \
  -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

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

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
`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

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
`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

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

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
`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

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
`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

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

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 '{}'

API Reference: Agent Nodes

POST /nodes/admin

Parameters

Request Body

Responses

Example Usage

GET /nodes/admin

Parameters

Responses

Example Usage

GET /nodes/admin/{node_id}

Parameters

Responses

Example Usage

PATCH /nodes/admin/{node_id}

Parameters

Request Body

Responses

Example Usage

DELETE /nodes/admin/{node_id}

Parameters

Responses

Example Usage

POST /nodes/admin/{node_id}/access

Parameters

Request Body

Responses

Example Usage

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

Parameters

Responses

Example Usage

POST /nodes/admin/mesh/reset

Parameters

Responses

Example Usage

GET /nodes/

Parameters

Responses

Example Usage

GET /nodes/{node_id}/status

Parameters

Responses

Example Usage

GET /nodes/{node_id}/terminal

Parameters

Responses

Example Usage

POST /nodes/{node_id}/dispatch

Parameters

Request Body

Responses

Example Usage

POST /nodes/{node_id}/cancel

Parameters

Responses

Example Usage

PATCH /nodes/preferences

Parameters

Request Body

Responses

Example Usage

GET /nodes/preferences

Parameters

Responses

Example Usage

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

Parameters

Responses

Example Usage

GET /nodes/provision/{node_id}

Parameters

Responses

Example Usage

GET /nodes/admin/{node_id}/download

Parameters

Responses

Example Usage

POST /nodes/validate-token

Parameters

POST `/nodes/admin`

GET `/nodes/admin`

GET `/nodes/admin/{node_id}`

PATCH `/nodes/admin/{node_id}`

DELETE `/nodes/admin/{node_id}`

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

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

POST `/nodes/admin/mesh/reset`

GET `/nodes/`

GET `/nodes/{node_id}/status`

GET `/nodes/{node_id}/terminal`

POST `/nodes/{node_id}/dispatch`

POST `/nodes/{node_id}/cancel`

PATCH `/nodes/preferences`

GET `/nodes/preferences`

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

GET `/nodes/provision/{node_id}`

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

POST `/nodes/validate-token`

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

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

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

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

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

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