This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
API Reference
All endpoints are prefixed with /api/v1/. Authentication via cookie aegis_token or
Authorization: Bearer <token>. Role abbreviations: A=admin, RL=red_lead, BL=blue_lead,
RT=red_tech, BT=blue_tech, V=viewer, Any=all authenticated.
Auth — /api/v1/auth
Method
Path
Auth
Description
POST
/auth/login
Public
Login with username+password (form-encoded). Sets aegis_token cookie.
POST
/auth/logout
Any
Revokes token (adds jti to Redis blacklist). Clears cookie.
GET
/auth/me
Any
Returns current user profile + role.
POST
/auth/change-password
Any
Change own password. Required if must_change_password=true.
Users — /api/v1/users
Method
Path
Auth
Description
GET
/users
A
List all users (paginated).
POST
/users
A
Create a new user. Sets must_change_password=true.
GET
/users/{id}
A
Get user by ID.
PATCH
/users/{id}
A
Update user (role, is_active, display_name, etc.).
DELETE
/users/{id}
A
Deactivate (soft-delete) a user.
GET
/users/me
Any
Get own profile.
PATCH
/users/me/preferences
Any
Update own UI preferences (theme, notifications, etc.).
Techniques — /api/v1/techniques
Method
Path
Auth
Description
GET
/techniques
Any
List techniques. Query: tactic_id, platform, coverage_status, search.
GET
/techniques/{mitre_id}
Any
Get technique by MITRE ID (e.g. T1059.001).
POST
/techniques
A
Create a custom technique (non-MITRE).
PATCH
/techniques/{mitre_id}
A
Update technique metadata.
PATCH
/techniques/{mitre_id}/review
RL,BL,A
Mark technique as needing review.
GET
/techniques/{mitre_id}/d3fend
Any
D3FEND countermeasure mappings for this technique.
Tests — /api/v1/tests
Method
Path
Auth
Description
GET
/tests
Any
List tests. Filters: state, technique_id, campaign_id, assigned_to.
POST
/tests
RL,BL,A
Create a new test in draft state.
POST
/tests/from-template
RL,BL,A
Create test(s) from a saved template.
GET
/tests/{id}
Any
Get full test detail including all fields.
PATCH
/tests/{id}
RL,BL,A
Update general fields (title, objective, technique, etc.). Draft/rejected only.
PATCH
/tests/{id}/classification
A
Set data_classification (confidential, restricted, etc.).
PATCH
/tests/{id}/red
RL,RT,A
Update red-side fields. State: red_executing.
PATCH
/tests/{id}/blue
BL,BT,A
Update blue-side fields. State: blue_evaluating.
POST
/tests/{id}/start-execution
RL,RT,A
Transition draft → red_executing.
POST
/tests/{id}/submit-red
RL,RT,A
Transition red_executing → blue_evaluating.
POST
/tests/{id}/submit-blue
BL,BT,A
Transition blue_evaluating → in_review.
POST
/tests/{id}/validate-red
RL,A
Approve/reject red side. State: in_review.
POST
/tests/{id}/validate-blue
BL,A
Approve/reject blue side. State: in_review.
POST
/tests/{id}/reopen
RL,BL,A
Transition rejected → draft.
POST
/tests/{id}/pause-timer
All except V
Pause elapsed time counter.
POST
/tests/{id}/resume-timer
All except V
Resume elapsed time counter.
PATCH
/tests/{id}/remediation
RL,BL,A
Update remediation status/notes (any state post-review).
GET
/tests/{id}/timeline
Any
Full audit trail of state changes and actions.
GET
/tests/{id}/retest-chain
Any
All tests in this retest lineage.
Evidence — /api/v1/tests/{id}/evidence & /api/v1/evidence
Method
Path
Auth
Description
POST
/tests/{id}/evidence
Role-dependent*
Upload evidence file. team=red or team=blue.
GET
/tests/{id}/evidence
Any
List all evidence files for a test.
GET
/evidence/{id}
Any
Get evidence metadata.
GET
/evidence/{id}/download
Any
Download evidence file from MinIO (signed URL or stream).
DELETE
/evidence/{id}
Own or RL,BL,A
Delete evidence file.
*red evidence: RL, RT, A | blue evidence: BL, BT, A. State restrictions apply (see Test-Lifecycle ).
Campaigns — /api/v1/campaigns
Method
Path
Auth
Description
GET
/campaigns
Any
List campaigns. Filters: status, type, date range.
POST
/campaigns
RL,BL,A
Create a new campaign.
GET
/campaigns/{id}
Any
Get campaign detail.
PATCH
/campaigns/{id}
RL,BL,A
Update campaign metadata.
POST
/campaigns/{id}/tests
RL,BL,A
Add a test to a campaign.
DELETE
/campaigns/{id}/tests/{ctid}
RL,BL,A
Remove a test from a campaign.
POST
/campaigns/{id}/activate
RL,BL,A
Transition draft → active.
POST
/campaigns/{id}/complete
RL,A
Transition active → completed.
GET
/campaigns/{id}/progress
Any
Count validated/total tests in campaign.
POST
/campaigns/from-threat-actor/{actor_id}
RL,BL,A
Auto-create campaign + tests from threat actor profile.
PATCH
/campaigns/{id}/schedule
RL,BL,A
Set start_date / end_date.
GET
/campaigns/{id}/history
Any
Campaign state change history.
Attack Paths — /api/v1/attack-paths
Method
Path
Auth
Description
GET
/attack-paths
Any
List attack paths.
POST
/attack-paths
All except V
Create an attack path (sequence of techniques).
GET
/attack-paths/{id}
Any
Get attack path detail.
PATCH
/attack-paths/{id}
All except V
Update attack path metadata.
DELETE
/attack-paths/{id}
RL,BL,A
Delete attack path.
POST
/attack-paths/{id}/steps
All except V
Add a step (technique) to attack path.
DELETE
/attack-paths/{id}/steps/{sid}
All except V
Remove a step.
POST
/attack-paths/{id}/executions
All except V
Start an execution of the attack path.
POST
/executions/{id}/start
All except V
Begin execution.
POST
/executions/{id}/steps/{sid}
All except V
Record step outcome.
POST
/executions/{id}/complete
All except V
Mark execution complete.
POST
/executions/{id}/abort
RL,BL,A
Abort execution.
Knowledge — /api/v1/knowledge
Method
Path
Auth
Description
GET
/knowledge/playbooks
Any
List playbooks. Filter by technique, type.
POST
/knowledge/playbooks
RL,BL,A
Create a playbook.
GET
/knowledge/playbooks/{id}
Any
Get playbook + versions list.
PATCH
/knowledge/playbooks/{id}
RL,BL,A
Update playbook (creates version snapshot).
DELETE
/knowledge/playbooks/{id}
RL,BL,A
Delete playbook.
GET
/knowledge/playbooks/{id}/versions
Any
List all versions of a playbook.
POST
/knowledge/playbooks/{id}/restore/{version}
RL,BL,A
Restore a previous version.
GET
/knowledge/lessons
Any
List lessons learned. Filter by severity, technique.
POST
/knowledge/lessons
RL,BL,A
Create a lesson learned.
GET
/knowledge/lessons/{id}
Any
Get lesson detail.
PATCH
/knowledge/lessons/{id}
RL,BL,A
Update lesson.
DELETE
/knowledge/lessons/{id}
RL,BL,A
Delete lesson.
GET
/knowledge/stats
Any
Summary: playbooks by type, lessons by severity.
Ownership — /api/v1/ownership
Method
Path
Auth
Description
GET
/ownership/assignments
Any
Technique-to-owner assignments.
POST
/ownership/assignments
RL,BL,A
Assign technique ownership.
PATCH
/ownership/assignments/{id}
RL,BL,A
Update assignment.
DELETE
/ownership/assignments/{id}
RL,BL,A
Remove assignment.
GET
/ownership/assets
Any
Asset ownership list.
POST
/ownership/assets
BL,A
Create asset ownership record.
GET
/ownership/revalidation-queue
BL,A
Techniques requiring revalidation.
POST
/ownership/revalidation-queue/generate
BL,A
Generate revalidation queue from infrastructure changes.
Risk — /api/v1/risk
Method
Path
Auth
Description
POST
/risk/compute
RL,BL,A
Trigger risk recomputation.
GET
/risk/profiles
Any
Risk profile per technique.
GET
/risk/matrix
Any
Risk matrix (impact ×
GET
/risk/summary
Any
Aggregate risk numbers.
GET
/risk/recommendations
Any
Prioritized list of techniques to test next.
GET
/risk/top
Any
Top N highest-risk uncovered techniques. ?limit=N
Alerts — /api/v1/alerts
Method
Path
Auth
Description
POST
/alerts/evaluate
RL,BL,A
Manually trigger evaluation of all enabled rules.
GET
/alerts/summary
Any
Alert counts by status, severity, rule type.
GET
/alerts
Any
List alert instances. Filters: status, severity, rule_type.
GET
/alerts/{id}
Any
Get alert instance detail.
POST
/alerts/{id}/acknowledge
RL,BL,A
Acknowledge an alert.
POST
/alerts/{id}/resolve
RL,BL,A
Resolve an alert.
POST
/alerts/{id}/dismiss
RL,BL,A
Dismiss an alert.
GET
/alerts/rules
Any
List alert rules.
POST
/alerts/rules
RL,BL,A
Create an alert rule.
GET
/alerts/rules/{id}
Any
Get rule detail.
PATCH
/alerts/rules/{id}
RL,BL,A
Update rule.
DELETE
/alerts/rules/{id}
A
Delete rule.
Dashboard — /api/v1/dashboard
Method
Path
Auth
Description
GET
/dashboard/kpis
Any
Key metrics: total techniques, covered %, tests, campaigns.
GET
/dashboard/executive
Any
Narrative executive summary.
GET
/dashboard/coverage-by-tactic
Any
Coverage breakdown per tactic.
GET
/dashboard/posture-history
Any
Historical coverage trend data.
GET
/dashboard/activity
Any
Recent activity feed (tests, campaigns, validations).
POST
/dashboard/posture-snapshot
RL,BL,A
Create an immediate posture snapshot.
Snapshots — /api/v1/snapshots
Method
Path
Auth
Description
GET
/snapshots
Any
List snapshots (paginated).
POST
/snapshots
RL,BL,A
Create a manual snapshot.
GET
/snapshots/{id}
Any
Get snapshot detail.
DELETE
/snapshots/{id}
A
Delete a snapshot.
GET
/snapshots/evolution
Any
Trend data: coverage over time.
GET
/snapshots/compare
Any
Diff two snapshots. Query: ?a=&b=
Reports — /api/v1/reports
Method
Path
Auth
Description
GET
/reports/coverage-summary
Any
Coverage data as JSON.
GET
/reports/coverage-csv
Any
Coverage data as CSV download.
GET
/reports/test-results
Any
Test results data as JSON.
GET
/reports/remediation-status
Any
Remediation tracking data.
GET
/reports/generate/purple-campaign/{id}
RL,BL,A,V
Full campaign report. ?format=pdf
GET
/reports/generate/coverage-summary
RL,BL,A,V
Coverage status report.
GET
/reports/generate/executive-summary
RL,BL,A,V
Executive briefing document.
GET
/reports/generate/quarterly-summary
RL,BL,A,V
Quarterly review report.
GET
/reports/generate/technique/{id}
RL,BL,A,V
Per-technique detail report.
Detection Lifecycle — /api/v1/detection-lifecycle
Method
Path
Auth
Description
GET
/detection-lifecycle/assets
Any
List detection assets.
POST
/detection-lifecycle/assets
BL,A
Create a detection asset.
GET
/detection-lifecycle/assets/{id}
Any
Get asset detail.
PATCH
/detection-lifecycle/assets/{id}
BL,A
Update asset.
DELETE
/detection-lifecycle/assets/{id}
BL,A
Delete asset.
POST
/detection-lifecycle/assets/{id}/techniques/{tid}
BL,A
Link asset to technique.
DELETE
/detection-lifecycle/assets/{id}/techniques/{tid}
BL,A
Unlink asset from technique.
GET
/detection-lifecycle/validations
Any
List detection validations.
POST
/detection-lifecycle/validations
BL,A
Create a validation record.
POST
/detection-lifecycle/validations/{id}/invalidate
BL,A
Invalidate (revoke) a validation.
GET
/detection-lifecycle/infrastructure-changes
Any
List infrastructure change records.
POST
/detection-lifecycle/infrastructure-changes
BL,A
Record an infrastructure change.
GET
/detection-lifecycle/dashboard
Any
Detection confidence per technique.
Detection Rules — /api/v1/detection-rules
Method
Path
Auth
Description
GET
/detection-rules
Any
List detection rules.
POST
/detection-rules
BL,A
Create detection rule.
GET
/detection-rules/{id}
Any
Get rule detail.
PATCH
/detection-rules/{id}
BL,A
Update rule.
DELETE
/detection-rules/{id}
BL,A
Delete rule.
POST
/detection-rules/evaluate
BL,BT,A
Record rule triggered/not-triggered for a test.
Test Templates — /api/v1/test-templates
Method
Path
Auth
Description
GET
/test-templates
Any
List templates.
POST
/test-templates
RL,BL,A
Create template from existing test or from scratch.
GET
/test-templates/{id}
Any
Get template detail.
PATCH
/test-templates/{id}
RL,BL,A
Update template.
DELETE
/test-templates/{id}
RL,BL,A
Delete template.
Webhooks — /api/v1/webhooks (admin only)
Method
Path
Auth
Description
GET
/webhooks
A
List configured webhooks.
POST
/webhooks
A
Create a webhook (URL, events, secret).
GET
/webhooks/{id}
A
Get webhook detail.
PATCH
/webhooks/{id}
A
Update webhook.
DELETE
/webhooks/{id}
A
Delete webhook.
POST
/webhooks/{id}/test
A
Send a test event to the webhook URL.
Webhook events: test.validated, test.state_changed, campaign.completed,
alert.fired, coverage.changed.
SSRF protection: webhook URLs are validated against private IP ranges before saving.
API Keys — /api/v1/api-keys
Method
Path
Auth
Description
GET
/api-keys
Any
List own API keys.
POST
/api-keys
Any
Create a new API key. Scope: read/write/admin.
DELETE
/api-keys/{id}
Own or A
Revoke an API key.
Keys are prefixed aegis_ and passed as Authorization: Bearer aegis_<hex>.
SSO — /api/v1/sso
Method
Path
Auth
Description
GET
/sso/status
Any
Whether SSO is configured and enabled.
PUT
/sso/config
A
Configure SAML 2.0 SSO settings.
GET
/sso/login
Public
Initiate SAML login redirect.
POST
/sso/callback
Public
SAML assertion callback.
GET
/sso/metadata
Public
Service provider metadata XML.
Other Modules
Module
Path prefix
Auth
Notes
Notifications
/notifications
Any (own)
GET list, PATCH mark-read
Audit Logs
/audit-logs
A
GET with filters
Jira
/jira
RL,BL,A
sync, issues
Threat Actors
/threat-actors
Any GET, RL,BL,A manage
Compliance
/compliance
Any
frameworks, controls, gaps
Analytics
/analytics
Any
trend analytics
Heatmap
/heatmap
Any
Coverage matrix
Scores
/scores
Any GET; A for config PATCH
Worklogs
/worklogs
Any create; own or A to read
OSINT
/osint
RL,BL,A
Data Sources
/data-sources
Any GET; A manage
System
/system
A (scheduler, sync); Public (health)