2026-01-14 03:09:18 +00:00
|
|
|
# REST API Reference\n\nThis document provides comprehensive documentation for all REST API endpoints in provisioning.\n\n## Overview\n\nProvisioning exposes two main REST APIs:\n\n- **Orchestrator API** (Port 8080): Core workflow management and batch operations\n- **Control Center API** (Port 9080): Authentication, authorization, and policy management\n\n## Base URLs\n\n- **Orchestrator**: `http://localhost:9090`\n- **Control Center**: `http://localhost:9080`\n\n## Authentication\n\n### JWT Authentication\n\nAll API endpoints (except health checks) require JWT authentication via the Authorization header:\n\n```\nAuthorization: Bearer <jwt_token>\n```\n\n### Getting Access Token\n\n```\nPOST /auth/login\nContent-Type: application/json\n\n{\n "username": "admin",\n "password": "password",\n "mfa_code": "123456"\n}\n```\n\n## Orchestrator API Endpoints\n\n### Health Check\n\n#### GET /health\n\nCheck orchestrator health status.\n\n**Response:**\n\n```\n{\n "success": true,\n "data": "Orchestrator is healthy"\n}\n```\n\n### Task Management\n\n#### GET /tasks\n\nList all workflow tasks.\n\n**Query Parameters:**\n\n- `status` (optional): Filter by task status (Pending, Running, Completed, Failed, Cancelled)\n- `limit` (optional): Maximum number of results\n- `offset` (optional): Pagination offset\n\n**Response:**\n\n```\n{\n "success": true,\n "data": [\n {\n "id": "uuid-string",\n "name": "create_servers",\n "command": "/usr/local/provisioning servers create",\n "args": ["--infra", "production", "--wait"],\n "dependencies": [],\n "status": "Completed",\n "created_at": "2025-09-26T10:00:00Z",\n "started_at": "2025-09-26T10:00:05Z",\n "completed_at": "2025-09-26T10:05:30Z",\n "output": "Successfully created 3 servers",\n "error": null\n }\n ]\n}\n```\n\n#### GET /tasks/{id}\n\nGet specific task status and details.\n\n**Path Parameters:**\n\n- `id`: Task UUID\n\n**Response:**\n\n```\n{\n "success": true,\n "data": {\n "id": "uuid-string",\n "name": "create_servers",\n "command": "/usr/local/provisioning servers create",\n "args": ["--infra", "production", "--wait"],\n "dependencies": [],\n "status": "Running",\n "created_at": "2025-09-26T10:00:00Z",\n "started_at": "2025-09-26T10:00:05Z",\n "completed_at": null,\n "output": null,\n "error": null\n }\n}\n```\n\n### Workflow Submission\n\n#### POST /workflows/servers/create\n\nSubmit server creation workflow.\n\n**Request Body:**\n\n```\n{\n "infra": "production",\n "settings": "config.ncl",\n "check_mode": false,\n "wait": true\n}\n```\n\n**Response:**\n\n```\n{\n "success": true,\n "data": "uuid-task-id"\n}\n```\n\n#### POST /workflows/taskserv/create\n\nSubmit task service workflow.\n\n**Request Body:**\n\n```\n{\n "operation": "create",\n "taskserv": "kubernetes",\n "infra": "production",\n "settings": "config.ncl",\n "check_mode": false,\n "wait": true\n}\n```\n\n**Response:**\n\n```\n{\n "success": true,\n "data": "uuid-task-id"\n}\n```\n\n#### POST /workflows/cluster/create\n\nSubmit cluster workflow.\n\n**Request Body:**\n\n```\n{\n "operation": "create",\n "cluster_type": "buildkit",\n "infra": "production",\n "settings": "config.ncl",\n "check_mode": false,\n "wait": true\n}\n```\n\n**Response:**\n\n```\n{\n "success": true,\n "data": "uuid-task-id"\n}\n```\n\n### Batch Operations\n\n#### POST /batch/execute\n\nExecute batch workflow operation.\n\n**Request Body:**\n\n```\n{\n "name": "multi_cloud_deployment",\n "version": "1.0.0",\n "storage_backend": "surrealdb",\n "parallel_limit": 5,\n "rollback_enabled": true,\n "operations": [\n {\n "id": "upcloud_servers",\n "type": "server_batch",\n "provider": "upcloud",\n "dependencies": [],\n "server_configs": [\n {"name": "web-01", "plan": "1xCPU-2 GB", "zone": "de-fra1"},\n {"name": "web-02", "plan": "1xCPU-2 GB", "zone": "us-nyc1"}\n ]\n },\n {\n "id": "aws_taskservs",\n "type": "taskserv_batch",\n "provider": "aws",\n
|
