<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->

# API Reference — Performing Adversary Emulation

## CALDERA REST API v2

### Endpoints

| Method | Endpoint | Description |
|---|---|---|
| `POST` | `/api/v2/adversaries` | Create adversary profile |
| `GET` | `/api/v2/adversaries` | List all adversary profiles |
| `POST` | `/api/v2/operations` | Launch an operation |
| `GET` | `/api/v2/operations/<id>` | Get operation status and chain |
| `PATCH` | `/api/v2/operations/<id>` | Update operation (pause/resume) |
| `DELETE` | `/api/v2/operations/<id>` | Delete operation |
| `GET` | `/api/v2/agents` | List connected agents |
| `DELETE` | `/api/v2/agents/<paw>` | Remove agent |
| `GET` | `/api/v2/abilities` | List all abilities |
| `GET` | `/api/v2/planners` | List available planners |

### Authentication

All requests require `KEY` header with API key:
```
KEY: ADMIN123
```

### Planners

| Planner | Behavior |
|---|---|
| `atomic` | Execute abilities one at a time in order |
| `batch` | Execute all abilities simultaneously |
| `buckets` | Group by ATT&CK tactic, execute tactic-by-tactic |
| `sequential` | Chain abilities based on fact dependencies |

### Link Status Codes

| Code | Meaning |
|---|---|
| `0` | Success |
| `-2` | Discarded |
| `-3` | Collected (awaiting execution) |
| `-4` | Untrusted |
| `1` | Failed |
| `124` | Timeout |

## Agent Script

```bash
# Create adversary profile
node agent.js create-adversary --name "APT29" --techniques T1566.001,T1059.001,T1003.001

# Launch operation
node agent.js launch --name "APT29-Run-001" --adversary-id <uuid>

# Check operation status
node agent.js status --operation-id <uuid>

# Record detection result
node agent.js record-detection --operation APT29-Run-001 --technique T1003.001 \
  --exec-time 2026-03-15T14:30:00Z --alert-time 2026-03-15T14:32:15Z

# List agents
node agent.js list-agents
```
