# DevOS v1 API Specification

## 1. API Style
Use versioned HTTP APIs under `/api/v1`.

All mutations use explicit DTOs and return structured resources/results.

## 2. Core Endpoints

### Auth
```text
POST /api/v1/auth/login
POST /api/v1/auth/logout
GET  /api/v1/auth/me
```

### Workspaces
```text
GET  /api/v1/workspaces
POST /api/v1/workspaces
GET  /api/v1/workspaces/:workspaceId
```

### Resources
```text
GET    /api/v1/resources
POST   /api/v1/resources
GET    /api/v1/resources/:id
PATCH  /api/v1/resources/:id
DELETE /api/v1/resources/:id
GET    /api/v1/resources/:id/relations
```

### Servers
```text
GET  /api/v1/servers
POST /api/v1/servers
GET  /api/v1/servers/:id
POST /api/v1/servers/:id/connect
GET  /api/v1/servers/:id/status
GET  /api/v1/servers/:id/containers
POST /api/v1/servers/:id/exec
POST /api/v1/servers/:id/restart
```

### Websites
```text
GET  /api/v1/websites
POST /api/v1/websites
GET  /api/v1/websites/:id
POST /api/v1/websites/:id/deploy
GET  /api/v1/websites/:id/logs
GET  /api/v1/websites/:id/health
```

### Deployments
```text
GET  /api/v1/deployments
GET  /api/v1/deployments/:id
POST /api/v1/deployments
POST /api/v1/deployments/:id/cancel
```

### Domains
```text
GET  /api/v1/domains
POST /api/v1/domains
GET  /api/v1/domains/:id
POST /api/v1/domains/:id/records
```

### Automation
```text
GET  /api/v1/automations
POST /api/v1/automations
GET  /api/v1/automations/:id
POST /api/v1/automations/:id/enable
POST /api/v1/automations/:id/disable
```

### AI
```text
POST /api/v1/ai/runs
GET  /api/v1/ai/runs/:id
POST /api/v1/ai/runs/:id/approve
```

## 3. Mutation Contract
Every mutation:
- validates a DTO
- checks workspace authorization
- determines risk
- writes an audit record
- emits domain events when appropriate
- returns a request/correlation identifier

## 4. Error Contract

```json
{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Resource was not found",
    "requestId": "..."
  }
}
```

Never expose stack traces, credentials or provider secrets through API errors.