# Orchestrator API Endpoints

Complete reference for Orchestrator REST API endpoints.

## Workflow Management

### Create Workflow

```http
POST /v1/workflows
Content-Type: application/json

{
  "name": "deployment-workflow",
  "description": "Deploy application",
  "config": {
    "tasks": [
      {
        "name": "validate",
        "action": "validate_config"
      },
      {
        "name": "deploy",
        "action": "deploy",
        "depends_on": ["validate"]
      }
    ]
  }
}
```

Response: `201 Created`

```json
{
  "id": "wf-12345",
  "name": "deployment-workflow",
  "status": "created",
  "created_at": "2026-01-16T12:00:00Z"
}
```

### Get Workflow

```http
GET /v1/workflows/:id
```

Response: `200 OK`

```json
{
  "id": "wf-12345",
  "name": "deployment-workflow",
  "status": "running",
  "progress": 45,
  "tasks": [...]
}
```

### List Workflows

```http
GET /v1/workflows?status=running&limit=10
```

### Execute Workflow

```http
POST /v1/workflows/:id/execute
```

### Cancel Workflow

```http
POST /v1/workflows/:id/cancel
```

## Task Management

### Get Task

```http
GET /v1/tasks/:id
```

Response: `200 OK`

```json
{
  "id": "task-67890",
  "name": "deploy-servers",
  "status": "running",
  "progress": 60,
  "started_at": "2026-01-16T12:05:00Z",
  "logs": "..."
}
```

### Get Task Logs

```http
GET /v1/tasks/:id/logs?lines=100&follow=true
```

### Retry Task

```http
POST /v1/tasks/:id/retry
```

## State Management

### Get Workflow State

```http
GET /v1/workflows/:id/state
```

### Save Checkpoint

```http
POST /v1/workflows/:id/checkpoint
{
  "name": "pre-deploy",
  "description": "State before deployment"
}
```

### Restore from Checkpoint

```http
POST /v1/workflows/:id/restore
{
  "checkpoint": "pre-deploy"
}
```

## Metrics & Monitoring

### Workflow Metrics

```http
GET /v1/workflows/:id/metrics
```

Response:

```json
{
  "duration_seconds": 245,
  "tasks_total": 5,
  "tasks_completed": 5,
  "tasks_failed": 0,
  "resource_usage": {
    "cpu_percent": 45,
    "memory_mb": 512
  }
}
```

### System Health

```http
GET /v1/health
```

Response: `200 OK`

```json
{
  "status": "healthy",
  "components": {
    "database": "healthy",
    "task_queue": "healthy",
    "cache": "healthy"
  }
}
```

## Related Documentation

- [REST API Overview](./rest-api.md)
- [Control Center API](./control-center-api.md)
- [Orchestrator Feature](../features/orchestrator.md)
