API Documentation
JSON API endpoints for programmatic access and automation. API Version: v1
Resource Endpoints
GET /api/hosts
List all hosts. Filter: ?env=, ?lifecycle_status=
GET /api/systems
List all systems. Filter: ?tier=
GET /api/systems/:slug
Get system details by slug
GET /api/instances
List all instances. Filter: ?env=, ?tier=, ?conformance_status=, ?lifecycle_status=
GET /api/services
List all Docker services
GET /api/ports
List all port allocations with conflict detection
Tags Endpoints
GET /api/tags
List all available tags (key/value pairs)
GET /api/instances/:ref/tags
Get tags for a specific instance
GET /api/hosts/:ref/tags
Get tags for a specific host
AI Context Endpoints
GET /api/ai/briefing?instance_ref=INST-007
PRIMARY AI ENDPOINT - Complete briefing with context, tech stack, gotchas, recent ops, LLM policy, and last session
GET /api/ai/context?system_ref=SYS-001
Get scoped context for an AI assistant including system info, instances, hosts, and LLM policy
GET /api/ai/inventory
Get full inventory for AI assistants. Filter: ?system_ref=
POST /api/ai/session
Update last_ai_session for an instance. Body: {instance_ref, summary, files_modified, todos_completed, todos_remaining}
Operations Log
GET /api/operations
List operations. Filter: ?instance_ref=, ?host_ref=, ?system_ref=, ?type=, ?limit=
POST /api/operations
Log an operation. Body: {instance_ref, operation_type, summary, details, performed_by, session_ref}
Docker State (Read)
GET /api/docker/containers
List actual container state across all hosts. Filter: ?host_ref=, ?state=
GET /api/docker/images
List Docker images across all hosts. Filter: ?host_ref=
Agent Ingestion (Auth Required)
POST /api/agent/v1/containers
Agent-only: Ingest container state. Header: Authorization: Bearer <token>. Body: {containers: [...]}
POST /api/agent/v1/images
Agent-only: Ingest image state. Header: Authorization: Bearer <token>. Body: {images: [...]}
Snapshot System
GET /api/snapshots
List snapshots. Filter: ?host_ref=, ?limit=
GET /api/snapshots/:id
Get snapshot detail with full container/image state
POST /api/snapshots
Force snapshot. Body: {host_ref, trigger_reason?, triggered_by?}
POST /api/snapshots/:id/archive
Promote snapshot to archive. Body: {archive_slot?, archive_label?, keep_until?}
GET /api/snapshots/archives
List all archives. Filter: ?host_ref=
GET /api/snapshots/compliance
Compliance checker. Shows all hosts and their snapshot compliance status
POST /api/snapshots/compliance/check
Run compliance check, auto-snapshot if needed. Body: {host_ref?, force_snapshot?}
PATCH /api/snapshots/settings/:host_ref
Update host snapshot settings. Body: {auto_snapshot_enabled?, max_archive_slots?, ...}