prvng_platform/provisioning-server/API_REFERENCE.md

# Provisioning API Reference

Complete API reference for the Provisioning API Server.

## Base URL

```
http://localhost:8083
```

## Authentication

All protected endpoints require JWT authentication via the `Authorization` header:

```
Authorization: Bearer <token>
```

## Response Format

### Success Response

```json
{
  "id": "string",
  "status": "pending|running|completed|failed|cancelled",
  "created_at": "2025-10-06T12:00:00Z",
  "updated_at": "2025-10-06T12:00:00Z",
  "result": {},
  "error": null
}
```

### Error Response

```json
{
  "error": "ERROR_CODE",
  "message": "Human readable error message",
  "code": "400"
}
```

## Endpoints

### Authentication

#### POST /v1/auth/login

Login and receive access token.

**Request:**
```json
{
  "username": "admin",
  "password": "admin123"
}
```

**Response:**
```json
{
  "token": "eyJhbGc...",
  "refresh_token": "eyJhbGc...",
  "expires_in": 86400
}
```

**Status Codes:**
- `200` - Success
- `401` - Invalid credentials

---

#### POST /v1/auth/refresh

Refresh access token using refresh token.

**Request:**
```json
{
  "refresh_token": "eyJhbGc..."
}
```

**Response:**
```json
{
  "token": "eyJhbGc...",
  "refresh_token": "eyJhbGc...",
  "expires_in": 86400
}
```

**Status Codes:**
- `200` - Success
- `401` - Invalid refresh token

---

### Servers

#### GET /v1/servers

List all servers.

**Headers:**
- `Authorization: Bearer <token>`

**Response:**
```json
[
  {
    "id": "srv-abc123",
    "hostname": "web-01",
    "provider": "upcloud",
    "plan": "2xCPU-4GB",
    "zone": "de-fra1",
    "ip_address": "10.0.0.1",
    "status": "running",
    "created_at": "2025-10-06T12:00:00Z"
  }
]
```

**Required Permission:** `server_read`

**Status Codes:**
- `200` - Success
- `401` - Unauthorized
- `403` - Forbidden

---

#### POST /v1/servers/create

Create a new server.

**Headers:**
- `Authorization: Bearer <token>`

**Request:**
```json
{
  "workspace": "production",
  "provider": "upcloud",
  "plan": "2xCPU-4GB",
  "hostname": "web-01",
  "zone": "de-fra1",
  "check_mode": false,
  "tags": ["web", "production"]
}
```

**Response:**
```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "created_at": "2025-10-06T12:00:00Z",
  "updated_at": "2025-10-06T12:00:00Z",
  "result": null,
  "error": null
}
```

**Required Permission:** `server_create`

**Status Codes:**
- `200` - Success
- `400` - Bad request (validation error)
- `401` - Unauthorized
- `403` - Forbidden

---

#### DELETE /v1/servers/{id}

Delete a server.

**Headers:**
- `Authorization: Bearer <token>`

**Request:**
```json
{
  "workspace": "production",
  "server_id": "srv-abc123",
  "force": false
}
```

**Response:**
```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "created_at": "2025-10-06T12:00:00Z",
  "updated_at": "2025-10-06T12:00:00Z",
  "result": null,
  "error": null
}
```

**Required Permission:** `server_delete`

**Status Codes:**
- `200` - Success
- `404` - Server not found
- `401` - Unauthorized
- `403` - Forbidden

---

#### GET /v1/servers/{id}/status

Get server status.

**Headers:**
- `Authorization: Bearer <token>`

**Response:**
```json
{
  "id": "srv-abc123",
  "hostname": "web-01",
  "provider": "upcloud",
  "plan": "2xCPU-4GB",
  "zone": "de-fra1",
  "ip_address": "10.0.0.1",
  "status": "running",
  "created_at": "2025-10-06T12:00:00Z"
}
```

**Required Permission:** `server_read`

**Status Codes:**
- `200` - Success
- `404` - Server not found
- `401` - Unauthorized
- `403` - Forbidden

---

### Taskservs

#### GET /v1/taskservs

List all taskservs.

**Headers:**
- `Authorization: Bearer <token>`

**Response:**
```json
[
  {
    "id": "tsk-xyz789",
    "name": "kubernetes",
    "version": "1.28.0",
    "servers": ["web-01", "web-02"],
    "status": "running",
    "created_at": "2025-10-06T12:00:00Z"
  }
]
```

**Required Permission:** `taskserv_read`

---

#### POST /v1/taskservs/create

Create a new taskserv.

**Headers:**
- `Authorization: Bearer <token>`

**Request:**
```json
{
  "workspace": "production",
  "name": "kubernetes",
  "servers": ["web-01", "web-02"],
  "config": {
    "version": "1.28.0"
  },
  "check_mode": false
}
```

**Response:**
```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "created_at": "2025-10-06T12:00:00Z",
  "updated_at": "2025-10-06T12:00:00Z",
  "result": null,
  "error": null
}
```

**Required Permission:** `taskserv_create`

---

#### DELETE /v1/taskservs/{id}

Delete a taskserv.

**Headers:**
- `Authorization: Bearer <token>`

**Request:**
```json
{
  "workspace": "production",
  "taskserv_id": "tsk-xyz789"
}
```

**Response:**
```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "created_at": "2025-10-06T12:00:00Z",
  "updated_at": "2025-10-06T12:00:00Z",
  "result": null,
  "error": null
}
```

**Required Permission:** `taskserv_delete`

---

### Workflows

#### POST /v1/workflows/submit

Submit a workflow.

**Headers:**
- `Authorization: Bearer <token>`

**Request:**
```json
{
  "workspace": "production",
  "workflow_type": "cluster_create",
  "parameters": {
    "cluster_name": "k8s-prod",
    "node_count": 3
  }
}
```

**Response:**
```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "created_at": "2025-10-06T12:00:00Z",
  "updated_at": "2025-10-06T12:00:00Z",
  "result": null,
  "error": null
}
```

**Required Permission:** `workflow_submit`

---

#### GET /v1/workflows/{id}

Get workflow details.

**Headers:**
- `Authorization: Bearer <token>`

**Response:**
```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "workflow_type": "cluster_create",
  "status": "running",
  "created_at": "2025-10-06T12:00:00Z",
  "updated_at": "2025-10-06T12:05:00Z"
}
```

**Required Permission:** `workflow_read`

---

#### POST /v1/workflows/{id}/cancel

Cancel a workflow.

**Headers:**
- `Authorization: Bearer <token>`

**Response:**
```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "cancelled",
  "created_at": "2025-10-06T12:00:00Z",
  "updated_at": "2025-10-06T12:10:00Z",
  "result": null,
  "error": null
}
```

**Required Permission:** `workflow_cancel`

---

### Operations

#### GET /v1/operations

List all operations.

**Headers:**
- `Authorization: Bearer <token>`

**Response:**
```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "created_at": "2025-10-06T12:00:00Z",
    "updated_at": "2025-10-06T12:05:00Z",
    "result": {
      "server_id": "srv-abc123"
    },
    "error": null
  }
]
```

**Required Permission:** `operation_read`

---

#### GET /v1/operations/{id}

Get operation status.

**Headers:**
- `Authorization: Bearer <token>`

**Response:**
```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "created_at": "2025-10-06T12:00:00Z",
  "updated_at": "2025-10-06T12:05:00Z",
  "result": {
    "server_id": "srv-abc123",
    "ip_address": "10.0.0.1"
  },
  "error": null
}
```

**Required Permission:** `operation_read`

---

#### POST /v1/operations/{id}/cancel

Cancel an operation.

**Headers:**
- `Authorization: Bearer <token>`

**Response:**
```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "cancelled",
  "created_at": "2025-10-06T12:00:00Z",
  "updated_at": "2025-10-06T12:10:00Z",
  "result": null,
  "error": null
}
```

**Required Permission:** `operation_cancel`

---

### Workspaces

#### GET /v1/workspaces

List all workspaces.

**Headers:**
- `Authorization: Bearer <token>`

**Response:**
```json
[
  {
    "name": "production",
    "path": "/opt/workspaces/production",
    "active": true,
    "last_used": "2025-10-06T12:00:00Z"
  }
]
```

**Required Permission:** `workspace_read`

---

#### POST /v1/workspaces/create

Create a workspace.

**Headers:**
- `Authorization: Bearer <token>`

**Request:**
```json
{
  "name": "staging",
  "path": "/opt/workspaces/staging",
  "activate": false
}
```

**Response:**
```json
{
  "name": "staging",
  "path": "/opt/workspaces/staging",
  "active": false,
  "last_used": null
}
```

**Required Permission:** `workspace_create`

---

### System

#### GET /health

Health check endpoint (no authentication required).

**Response:**
```json
{
  "status": "healthy",
  "version": "0.1.0",
  "uptime_seconds": 3600
}
```

**Status Codes:**
- `200` - Server is healthy

---

#### GET /v1/metrics

Get server metrics.

**Headers:**
- `Authorization: Bearer <token>`

**Response:**
```json
{
  "uptime_seconds": 3600,
  "tasks": {
    "total": 42,
    "running": 3
  }
}
```

**Required Permission:** `system_metrics`

---

## Status Codes

- `200` - OK
- `400` - Bad Request
- `401` - Unauthorized
- `403` - Forbidden
- `404` - Not Found
- `409` - Conflict
- `500` - Internal Server Error
- `503` - Service Unavailable

## Rate Limiting

Currently not implemented. Future versions may include:
- Per-user rate limits
- IP-based rate limits
- Operation-specific limits

## Pagination

Currently not implemented. All list endpoints return complete results.

Future versions may include:
- `?page=1&per_page=20`
- Link headers for pagination
- Total count in response

## Filtering

Currently not implemented. Future versions may include:
- `?status=running`
- `?workspace=production`
- `?created_after=2025-10-01`