> ## Documentation Index > Fetch the complete documentation index at: https://o1.network/docs/llms.txt > Use this file to discover all available pages before exploring further. # Nodes # Nodes API Reference Manage cloud infrastructure, servers, and virtual machines through the Nodes API. This API provides comprehensive infrastructure management capabilities across multiple cloud providers. ## Endpoints Overview | Method | Endpoint | Description | | ------ | ---------------------------- | ------------------------- | | GET | `/api/nodes` | List all configured nodes | | POST | `/api/nodes/add` | Add a new node | | PUT | `/api/nodes/edit` | Edit an existing node | | GET | `/api/nodes/{nodeName}` | Get specific node details | | POST | `/api/nodes/test-connection` | Test SSH connection | | POST | `/api/nodes/verify` | Verify node connection | | POST | `/api/nodes/execute` | Execute command on node | | POST | `/api/nodes/state/{action}` | Control application state | ## SSH Key Management ### List SSH Keys ```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} GET /api/nodes/ssh-keys ``` **Response:** ```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} { "success": true, "keys": [ { "id": "key-123456", "name": "my-ssh-key", "path": "/uploads/keys/my-ssh-key", "publicKey": "ssh-rsa AAAA...", "createdAt": "2024-01-15T10:30:00Z" } ] } ``` ### Add SSH Key ```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} POST /api/nodes/ssh-keys ``` **Request Body (multipart/form-data):** * `name` (string, required): Key name * `privateKey` (file, optional): Private key file * `privateKeyContent` (string, optional): Private key content **Response:** ```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} { "success": true, "key": { "id": "key-123456", "name": "my-ssh-key", "path": "/uploads/keys/my-ssh-key", "publicKey": "ssh-rsa AAAA...", "createdAt": "2024-01-15T10:30:00Z" }, "message": "SSH key added successfully" } ``` ## Node Management ### List All Nodes ```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} GET /api/nodes ``` **Response:** ```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} { "all": { "hosts": { "test-anvil-01": { "name": "test-anvil-01", "host": "3.84.243.191", "user": "ubuntu", "port": "22", "provider": "AWS", "location": "us-east-1", "instance_type": "t2.micro", "infrastructure": { "instance_id": "i-1234567890abcdef0", "operated_by": "o1", "provisioned_at": "2024-01-15T10:30:00Z" } } }, "children": { "anvil": { "type": "application", "hosts": { "test-anvil-01": { "vars": { "anvil_port": 8545, "accounts": 10 }, "deployment_mode": "binary", "last_deployment": "2024-01-15T10:30:00Z" } } } } } } ``` ### Add a New Node ```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} POST /api/nodes/add ``` **Request Body (multipart/form-data):** * `name` (string, required): Unique node name * `host` (string, required): Hostname or IP address * `user` (string, required): SSH username * `port` (string, optional): SSH port (default: 22) * `password` (string, optional): SSH password * `ansible_ssh_private_key_file` (file, optional): SSH private key * `provider` (string, optional): Cloud provider (AWS, Azure, GCP, DigitalOcean) * `location` (string, optional): Region/location * `instance_type` (string, optional): Instance type/size **Response:** ```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} { "success": true, "message": "Node added successfully" } ``` ### Get Node Details ```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} GET /api/nodes/{nodeName} ``` **Parameters:** * `nodeName` (path): Name of the node **Response:** ```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} { "success": true, "node": { "name": "test-anvil-01", "host": "3.84.243.191", "user": "ubuntu", "port": "22", "provider": "AWS", "location": "us-east-1", "instance_type": "t2.micro", "infrastructure": { "instance_id": "i-1234567890abcdef0", "operated_by": "o1", "provisioned_at": "2024-01-15T10:30:00Z" }, "metadata": { "os": "Ubuntu 22.04.3 LTS", "architecture": "x86_64", "kernel": "5.15.0-91-generic", "cpu_cores": 2, "memory_mb": 8192, "disk_gb": 100, "collected_at": "2024-01-15T10:30:00Z" }, "deployed_apps": [ { "name": "Anvil", "version": "1.0.0", "deployment_mode": "binary", "deployed_at": "2024-01-15T10:30:00Z", "status": "running" } ] } } ``` ## Cloud Instance Management ### Launch Cloud Instance ```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} POST /api/nodes/launch-instance ``` **Request Body (JSON):** ```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} { "credentialName": "production-aws", "provider": "AWS", "region": "us-east-1", "instanceType": "t2.micro", "name": "web-server-01", "sshKeyName": "my-key-pair", "createSecurityGroup": true, "volumeSize": 50, "tags": { "Environment": "production", "Project": "web-app" } } ``` **Response:** ```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} { "success": true, "instance": { "instanceId": "i-1234567890abcdef0", "name": "web-server-01", "publicIp": "3.84.243.191", "privateIp": "10.0.1.100", "status": "running", "provider": "AWS", "region": "us-east-1", "instanceType": "t2.micro", "launchTime": "2024-01-15T10:30:00Z" }, "message": "Instance launched successfully" } ``` ### Terminate Instance ```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} POST /api/nodes/terminate-instance ``` **Request Body (JSON):** ```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} { "nodeName": "web-server-01" } ``` **Response:** ```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} { "success": true, "message": "Instance terminated successfully" } ``` ### Restart Instance ```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} POST /api/nodes/restart-instance ``` **Request Body (JSON):** ```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} { "nodeName": "web-server-01" } ``` **Response:** ```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} { "success": true, "message": "Instance restarted successfully" } ``` ## Connection Management ### Test Connection ```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} POST /api/nodes/test-connection ``` **Request Body (multipart/form-data):** * `host` (string, required): Hostname or IP * `user` (string, required): SSH username * `port` (string, optional): SSH port * `password` (string, optional): SSH password * `ansible_ssh_private_key_file` (file, optional): SSH private key **Response:** ```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} { "message": "Connection successful", "success": true } ``` ### Verify Node ```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} POST /api/nodes/verify ``` **Request Body (JSON):** ```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} { "name": "test-anvil-01" } ``` **Response:** ```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} { "success": true, "message": "Node verified successfully" } ``` ### Execute Command ```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} POST /api/nodes/execute ``` **Request Body (JSON):** ```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} { "node": "test-anvil-01", "application": "Anvil", "command": "docker ps", "setup_mode": "docker", "args": { "filter": "name=anvil" } } ``` **Response:** ```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} { "success": true, "error": null, "output": "CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES", "raw": "Full command output..." } ``` ## Resource Management ### Add Firewall Rule ```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} POST /api/nodes/{nodeName}/resources/firewall ``` **Request Body (JSON):** ```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} { "protocol": "tcp", "port": "80", "source": "0.0.0.0/0", "description": "Allow HTTP traffic" } ``` **Response:** ```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} { "success": true, "rule": { "id": "rule-123456", "protocol": "tcp", "port": "80", "source": "0.0.0.0/0", "description": "Allow HTTP traffic", "createdBy": "o1" } } ``` ### Create Volume ```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} POST /api/nodes/{nodeName}/resources/volumes ``` **Request Body (JSON):** ```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} { "sizeGb": 100, "volumeType": "gp3", "device": "/dev/sdf", "description": "Application data volume" } ``` **Response:** ```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} { "success": true, "volume": { "id": "vol-12345678", "sizeGb": 100, "volumeType": "gp3", "device": "/dev/sdf", "description": "Application data volume", "attachedAt": "2024-01-15T10:30:00Z" } } ``` ## Discovery & Exploration ### Discover Cloud Instances ```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} POST /api/nodes/discover-instances ``` **Request Body (multipart/form-data):** * `credentials` (string, required): JSON string with provider credentials * `saveCredentials` (string, optional): Whether to save credentials * `credentialName` (string, optional): Name for saved credentials **Response:** ```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} { "instances": [ { "instanceId": "i-1234567890abcdef0", "name": "test-anvil-01", "publicIp": "3.84.243.191", "privateIp": "10.0.1.100", "status": "running", "provider": "AWS", "region": "us-east-1", "instanceType": "t2.micro" } ], "credentialsSaved": true } ``` ### Get Instance Types ```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} GET /api/nodes/instance-types/{provider}/{region} ``` **Parameters:** * `provider` (path): Cloud provider (AWS, Azure, GCP, DigitalOcean) * `region` (path): Cloud region **Response:** ```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} { "success": true, "instanceTypes": [ { "name": "t2.micro", "vcpus": 1, "memory": 1024, "price": 0.0116 }, { "name": "t2.small", "vcpus": 1, "memory": 2048, "price": 0.023 } ] } ``` ## Error Responses Common error responses for Nodes API: ```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} { "success": false, "error": "Node not found", "details": { "nodeName": "non-existent-node" } } ``` ```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} { "success": false, "error": "SSH connection failed", "details": { "host": "192.168.1.100", "user": "ubuntu", "output": "Connection timeout" } } ``` ## Best Practices ### Security * Use SSH keys instead of passwords whenever possible * Limit SSH access to specific IP ranges * Regularly rotate SSH keys and credentials * Monitor failed connection attempts ### Performance * Use connection pooling for frequent operations * Cache instance type information when possible * Implement proper error handling and retry logic * Monitor resource usage and API limits ### Automation * Use infrastructure-as-code approaches * Implement proper state management * Set up monitoring and alerting * Document all operational procedures For detailed schema definitions, refer to the OpenAPI specification published alongside the backend service.