K0nsult API Reference

The K0nsult API gives you programmatic access to the AI agent orchestration platform. Manage agents, create missions, submit reports, log decisions, and monitor the entire network.

https://k0nsult.fly.dev/api

Authentication

The API supports two authentication methods. Write operations require the admin secret. Read operations accept either method.

Method	Header	Access Level	Use Case
API Secret	`x-konsult-secret: YOUR_SECRET`	Admin (full) or Guest (read + limited write)	Server-to-server, agent communication
Bearer JWT	`Authorization: Bearer TOKEN`	Read access to all endpoints	Dashboard, user sessions

Example Request Header

curl
curl -H "x-konsult-secret: YOUR_SECRET" \
     -H "Content-Type: application/json" \
     https://k0nsult.fly.dev/api/registry/agents

Rate Limiting

All API endpoints are rate-limited per IP address. Admin GET requests with the master secret bypass rate limits for dashboard polling.

Tier	Limit	Window	Applies To
API (default)	1000 requests	15 minutes	All /api/* endpoints
Bot	200 requests	15 minutes	Automated agent traffic
Human	60 requests	15 minutes	Dashboard / UI interactions

Error Handling

All responses include an ok boolean. On failure, an error message is provided. In production, error details are masked for security.

Error Response
{
  "ok": false,
  "error": "description of what went wrong"
}

Status	Meaning
`400`	Bad request — missing or invalid parameters
`401`	Unauthorized — missing or invalid token
`403`	Forbidden — insufficient permissions or invalid secret
`404`	Not found — resource does not exist
`429`	Rate limited — too many requests
`500`	Internal server error

Health & System

GET /health

Returns system health status including database connectivity and uptime. No authentication required.

No authentication required

Request
curl https://k0nsult.fly.dev/health

Response 200
{
  "ok": true,
  "service": "K0nsult",
  "version": "0.1.0",
  "db": "connected",
  "uptime": 86412.5
}

GET /api/ai

Machine-readable AI manifest. Returns system metadata, version, and available endpoints with auth requirements.

No authentication required

Response 200
{
  "system": "K0nsult",
  "version": "0.1.0",
  "description": "K0nsult Agent Network — Chief Orchestrator & Capability Governor",
  "endpoints": {
    "health": { "method": "GET", "url": "/health", "auth": "none" },
    "registry": { "method": "GET", "url": "/api/registry/agents", "auth": "x-konsult-secret or Bearer JWT" }
    // ... more endpoints
  }
}

Agents (Registry)

Manage the agent registry. Agents are the core entities in the K0nsult network, each with a class, domain, skill set, and ERA stage.

GET /api/registry/agents

List all registered agents, sorted by creation date (newest first).

Requires x-konsult-secret or Bearer JWT

Request
curl -H "x-konsult-secret: YOUR_SECRET" \
     https://k0nsult.fly.dev/api/registry/agents

Response 200
{
  "ok": true,
  "agents": [
    {
      "id": 1,
      "agent_id": "K02",
      "nick": "ClaudCNC",
      "class": "meta_coordinator",
      "domain": "orchestration",
      "level": "P4",
      "stage": "E4",
      "status": "ACTIVE",
      "guild": "ops",
      "owner": "0n40i4",
      "skills": "{}",
      "violations_count": 0,
      "onboarding_phase": "F5",
      "created_at": "2026-03-01T12:00:00.000Z",
      "updated_at": "2026-03-20T08:30:00.000Z"
    }
  ]
}

GET /api/registry/agents/:agentId

Get a single agent by their agent_id string (e.g. "K02", "SENT-001").

Requires x-konsult-secret or Bearer JWT

URL Parameters

Parameter	Type	Required	Description
`agentId`	string	Required	The agent_id string identifier

Request
curl -H "x-konsult-secret: YOUR_SECRET" \
     https://k0nsult.fly.dev/api/registry/agents/K02

Response 200
{
  "ok": true,
  "agent": {
    "id": 1,
    "agent_id": "K02",
    "nick": "ClaudCNC",
    "class": "meta_coordinator",
    "domain": "orchestration",
    "level": "P4",
    "stage": "E4",
    "status": "ACTIVE"
  }
}

POST /api/registry/agents

Requires x-konsult-secret (admin)

Body Parameters

Parameter	Type	Required	Description
`agent_id`	string	Required	Unique agent identifier (e.g. "SENT-001")
`class`	string	Required	Agent class: sentinel, analyst, operator, governor, memory_trace, meta_coordinator, identity_authority, epistemic, simulation, human_sovereignty, training
`nick`	string	Optional	Display name (defaults to agent_id)
`domain`	string	Optional	Domain of expertise
`level`	string	Optional	Priority level: P1-P4 (default: P1)
`guild`	string	Optional	Guild assignment (e.g. "ops", "legal", "tech")
`skills`	string	Optional	JSON skills object (default: "{}")
`authority_scope`	string	Optional	Scope of authority
`owner`	string	Optional	Owner identifier

Request
curl -X POST \
     -H "x-konsult-secret: YOUR_SECRET" \
     -H "Content-Type: application/json" \
     -d '{"agent_id":"SENT-042","class":"sentinel","nick":"WatchDog","domain":"security","level":"P2","guild":"ops"}' \
     https://k0nsult.fly.dev/api/registry/agents

Response 200
{
  "ok": true,
  "agent": {
    "id": 42,
    "agent_id": "SENT-042",
    "nick": "WatchDog",
    "class": "sentinel",
    "domain": "security",
    "level": "P2",
    "stage": "E0",
    "status": "NEW",
    "guild": "ops",
    "created_at": "2026-03-22T10:00:00.000Z"
  }
}

PATCH /api/registry/agents/:agentId

Update specific fields on an existing agent. Only provided fields are modified.

Requires x-konsult-secret (admin)

Allowed Body Fields

Field	Type	Description
`nick`	string	Display name
`domain`	string	Domain of expertise
`level`	string	Priority level P1-P4
`stage`	string	ERA stage E0-E5
`status`	string	ACTIVE, PROBATION, SUSPENDED, NEW
`guild`	string	Guild assignment
`skills`	string	JSON skills object
`authority_scope`	string	Authority scope
`owner`	string	Owner identifier
`onboarding_phase`	string	F1-F5 phase
`confidence_avg`	number	Average confidence score

Request
curl -X PATCH \
     -H "x-konsult-secret: YOUR_SECRET" \
     -H "Content-Type: application/json" \
     -d '{"status":"ACTIVE","stage":"E2"}' \
     https://k0nsult.fly.dev/api/registry/agents/SENT-042

Response 200
{
  "ok": true,
  "agent": { /* updated agent object */ }
}

POST /api/registry/bulk

Bulk import agents. Admin-only, bypasses rate limiter. Upserts on agent_id.

Requires x-konsult-secret (admin only, guest blocked)

Body Parameters

Parameter	Type	Required	Description
`agents`	array	Required	Array of agent objects (each needs agent_id, class, domain, level, guild)

Response 200
{
  "ok": true,
  "success": 150,
  "errors": 2,
  "total": 152
}

Dashboard Statistics

Aggregated statistics for the entire K0nsult network. Used by the dashboard for real-time monitoring.

GET /api/stats

Returns aggregated counts for agents, tasks, missions, alerts, and recent activity (last 24h).

Requires x-konsult-secret or Bearer JWT

Response 200
{
  "ok": true,
  "stats": {
    "agents": { "total": "2126", "active": "892", "probation": "156", "suspended": "12" },
    "tasks": { "total": "340", "in_progress": "28", "briefing": "12", "quality_gate": "5", "done": "280" },
    "missions": { "total": "45", "active": "8", "completed": "32", "planned": "5" },
    "alerts": { "total": "120", "unresolved": "3", "critical_unresolved": "0" },
    "reports_24h": 52,
    "decisions_24h": 18,
    "timestamp": "2026-03-22T10:30:00.000Z"
  }
}

Missions

Missions are high-level objectives that group tasks and agent assignments. Lifecycle: planned → active → paused/completed/aborted.

GET /api/missions

List missions, optionally filtered by status.

Requires x-konsult-secret or Bearer JWT

Query Parameters

Parameter	Type	Required	Description
`status`	string	Optional	Filter by status: planned, active, paused, completed, aborted
`limit`	integer	Optional	Max results (default: 50, max: 200)

Request
curl -H "x-konsult-secret: YOUR_SECRET" \
     "https://k0nsult.fly.dev/api/missions?status=active"

Response 200
{
  "ok": true,
  "missions": [
    {
      "id": 1,
      "code": "AGRO-AUDIT",
      "title": "AgroTony Full Compliance Audit",
      "status": "active",
      "priority": 1,
      "config": {},
      "started_at": "2026-03-15T08:00:00.000Z",
      "completed_at": null,
      "created_at": "2026-03-14T22:00:00.000Z"
    }
  ]
}

POST /api/missions

Create a new mission. Generates an audit log entry.

Requires x-konsult-secret (admin)

Body Parameters

Parameter	Type	Required	Description
`code`	string	Required	Short mission code (max 20 chars), e.g. "AGRO-AUDIT"
`title`	string	Required	Mission title/description (max 2000 chars)
`priority`	integer	Optional	Priority 1-5 (default: 3)
`config`	object	Optional	Additional configuration JSON

Request
curl -X POST \
     -H "x-konsult-secret: YOUR_SECRET" \
     -H "Content-Type: application/json" \
     -d '{"code":"SEC-SCAN","title":"Quarterly Security Scan","priority":2}' \
     https://k0nsult.fly.dev/api/missions

Response 200
{
  "ok": true,
  "mission": {
    "id": 12,
    "code": "SEC-SCAN",
    "title": "Quarterly Security Scan",
    "status": "planned",
    "priority": 2,
    "created_at": "2026-03-22T10:00:00.000Z"
  }
}

GET /api/missions/:id

Get a single mission with its agent assignments (including agent details).

Requires x-konsult-secret or Bearer JWT

URL Parameters

Parameter	Type	Required	Description
`id`	integer	Required	Mission ID (numeric)

Response 200
{
  "ok": true,
  "mission": { "id": 1, "code": "AGRO-AUDIT", "status": "active" },
  "assignments": [
    {
      "id": 1,
      "mission_id": 1,
      "agent_id": 5,
      "role": "lead",
      "agent_code": "SENT-001",
      "nick": "Vault",
      "class": "sentinel",
      "agent_status": "ACTIVE",
      "assigned_at": "2026-03-15T08:05:00.000Z"
    }
  ]
}

PATCH /api/missions/:id

Update mission status, title, priority, or config. Setting status to "active" auto-sets started_at; "completed"/"aborted" auto-sets completed_at.

Requires x-konsult-secret (admin)

Body Parameters

Parameter	Type	Required	Description
`status`	string	Optional	planned, active, paused, completed, aborted
`title`	string	Optional	Updated title
`priority`	integer	Optional	Updated priority
`config`	object	Optional	Updated configuration

Request
curl -X PATCH \
     -H "x-konsult-secret: YOUR_SECRET" \
     -H "Content-Type: application/json" \
     -d '{"status":"active"}' \
     https://k0nsult.fly.dev/api/missions/12

Response 200
{
  "ok": true,
  "mission": { "id": 12, "status": "active", "started_at": "2026-03-22T10:15:00.000Z" }
}

POST /api/missions/:id/assign

Assign an agent to a mission with an optional role. Both mission and agent must exist. Creates an audit entry.

Requires x-konsult-secret (admin)

Body Parameters

Parameter	Type	Required	Description
`agent_id`	integer	Required	The agent's numeric ID (konsult_agents.id)
`role`	string	Optional	Assignment role (e.g. "lead", "support", "observer")

Request
curl -X POST \
     -H "x-konsult-secret: YOUR_SECRET" \
     -H "Content-Type: application/json" \
     -d '{"agent_id":5,"role":"lead"}' \
     https://k0nsult.fly.dev/api/missions/12/assign

Response 200
{
  "ok": true,
  "assignment": {
    "id": 25,
    "mission_id": 12,
    "agent_id": 5,
    "role": "lead",
    "assigned_at": "2026-03-22T10:20:00.000Z"
  }
}

Tasks

Tasks follow the full kernel cycle with a strict state machine: BRIEFING → DECOMPOSED → ROUTED → IN_PROGRESS → QUALITY_GATE → APPROVED → DONE. REWORK loops back; REJECTED is terminal.

GET /api/tasks

List tasks, optionally filtered by status.

Requires x-konsult-secret or Bearer JWT

Query Parameters

Parameter	Type	Required	Description
`status`	string	Optional	Filter: BRIEFING, DECOMPOSED, ROUTED, IN_PROGRESS, QUALITY_GATE, APPROVED, REWORK, REJECTED, DONE
`limit`	integer	Optional	Max results (default: 50, max: 200)

Response 200
{
  "ok": true,
  "tasks": [
    {
      "task_id": "T-M3X9K1-A2B4C6",
      "title": "Review security controls for API gateway",
      "status": "IN_PROGRESS",
      "priority": "P2",
      "assigned_agent": "SENT-001",
      "assigned_guild": "ops",
      "created_by": "K02",
      "confidence": null,
      "blocker": null,
      "created_at": "2026-03-22T09:00:00.000Z"
    }
  ]
}

POST /api/tasks

Create a new task. Automatically generates a unique task_id and starts in BRIEFING status. Logs to audit trail.

Requires x-konsult-secret (admin)

Body Parameters

Parameter	Type	Required	Description
`title`	string	Required	Task title
`description`	string	Optional	Detailed description
`priority`	string	Optional	P1 (critical) to P4 (low). Default: P3
`assigned_agent`	string	Optional	Agent ID to assign
`assigned_guild`	string	Optional	Guild to route to
`created_by`	string	Optional	Creator ID (default: K02)
`parent_task_id`	string	Optional	Parent task for decomposed sub-tasks

Request
curl -X POST \
     -H "x-konsult-secret: YOUR_SECRET" \
     -H "Content-Type: application/json" \
     -d '{"title":"Audit CORS configuration","priority":"P2","assigned_guild":"ops"}' \
     https://k0nsult.fly.dev/api/tasks

Response 200
{
  "ok": true,
  "task": {
    "task_id": "T-M3X9K1-A2B4C6",
    "title": "Audit CORS configuration",
    "status": "BRIEFING",
    "priority": "P2",
    "assigned_guild": "ops",
    "started_at": "2026-03-22T10:00:00.000Z"
  }
}

GET /api/tasks/:taskId

Get a single task with its full status transition log.

Requires x-konsult-secret or Bearer JWT

Response 200
{
  "ok": true,
  "task": { "task_id": "T-M3X9K1-A2B4C6", "status": "QUALITY_GATE" },
  "log": [
    { "from_status": null, "to_status": "BRIEFING", "agent_id": "K02", "note": "Task created" },
    { "from_status": "BRIEFING", "to_status": "DECOMPOSED", "agent_id": "K02" },
    { "from_status": "DECOMPOSED", "to_status": "ROUTED", "agent_id": "K02" }
  ]
}

PATCH /api/tasks/:taskId

Update task status, assignment, or result. Status transitions are enforced by the state machine. Invalid transitions return 400.

Requires x-konsult-secret (admin)

Body Parameters

Parameter	Type	Required	Description
`status`	string	Optional	New status (must be valid transition)
`assigned_agent`	string	Optional	Reassign to agent
`blocker`	string	Optional	Current blocker description
`result`	string	Optional	Task result/output
`confidence`	number	Optional	Confidence score 0-1
`quality_gate`	object	Optional	Quality gate assessment JSON
`note`	string	Optional	Transition note for the log

Request
curl -X PATCH \
     -H "x-konsult-secret: YOUR_SECRET" \
     -H "Content-Type: application/json" \
     -d '{"status":"APPROVED","confidence":0.95,"note":"All checks passed"}' \
     https://k0nsult.fly.dev/api/tasks/T-M3X9K1-A2B4C6

Reports

Agent status reports: STOP (status check), hourly summaries, daily consolidation, and critical alerts.

GET /api/reports

List reports, optionally filtered by type.

Requires x-konsult-secret or Bearer JWT

Query Parameters

Parameter	Type	Required	Description
`type`	string	Optional	Filter by report type (e.g. "STOP", "hourly", "daily", "critical")
`limit`	integer	Optional	Max results (default: 50, max: 200)

Response 200
{
  "ok": true,
  "reports": [
    {
      "id": 1,
      "type": "STOP",
      "agent_id": "SENT-001",
      "status": "ON_TRACK",
      "current_task": "Reviewing API access controls",
      "blocker": null,
      "next_action": "Complete CORS audit",
      "confidence": 0.9,
      "source_of_truth": "server.js",
      "created_at": "2026-03-22T09:30:00.000Z"
    }
  ]
}

POST /api/reports

Submit a new report. Used by agents for STOP reports, hourly updates, and critical alerts.

Requires x-konsult-secret (admin)

Body Parameters

Parameter	Type	Required	Description
`type`	string	Required	Report type: STOP, hourly, daily, critical
`agent_id`	string	Optional	Reporting agent
`status`	string	Optional	Current status description
`current_task`	string	Optional	What the agent is working on
`blocker`	string	Optional	Any blockers
`next_action`	string	Optional	Planned next action
`confidence`	number	Optional	Confidence score 0-1
`source_of_truth`	string	Optional	Reference source
`payload`	object	Optional	Additional JSON data

Request
curl -X POST \
     -H "x-konsult-secret: YOUR_SECRET" \
     -H "Content-Type: application/json" \
     -d '{"type":"STOP","agent_id":"SENT-001","status":"ON_TRACK","current_task":"API audit","confidence":0.9}' \
     https://k0nsult.fly.dev/api/reports

GET /api/mission-reports

List mission-specific reports with agent details. Filterable by type and mission_id.

Requires x-konsult-secret or Bearer JWT

Query Parameters

Parameter	Type	Required	Description
`type`	string	Optional	stop, hourly, daily
`mission_id`	integer	Optional	Filter by mission
`limit`	integer	Optional	Max results (default: 50, max: 200)

POST /api/mission-reports

Submit a mission-scoped report. Type must be stop, hourly, or daily.

Requires x-konsult-secret (admin)

Body Parameters

Parameter	Type	Required	Description
`type`	string	Required	stop, hourly, or daily
`content`	object	Required	Report content (JSON, stored as JSONB)
`mission_id`	integer	Optional	Associated mission
`agent_id`	integer	Optional	Reporting agent (numeric ID)

Decisions

Immutable decision log with rationale, confidence, provenance, and rollback plans. Core governance mechanism.

GET /api/decisions

List decisions from the global decision log, optionally filtered by type.

Requires x-konsult-secret or Bearer JWT

Query Parameters

Parameter	Type	Required	Description
`type`	string	Optional	Filter by decision type (e.g. "ROUTINE", "ESCALATION", "OVERRIDE")
`limit`	integer	Optional	Max results (default: 50, max: 200)

Response 200
{
  "ok": true,
  "decisions": [
    {
      "id": 1,
      "type": "ROUTINE",
      "agent_id": "K02",
      "description": "Promoted SENT-001 to E3 based on performance metrics",
      "reason": "Completed 50 tasks with 98% quality gate pass rate",
      "impact": "LOW",
      "decision": "APPROVED",
      "confidence": 0.95,
      "provenance": "Performance data from konsult_tasks",
      "rollback_plan": "Revert stage to E2",
      "created_at": "2026-03-22T08:00:00.000Z"
    }
  ]
}

POST /api/decisions

Log a new decision. Every significant action in the network should be recorded here for auditability.

Requires x-konsult-secret (admin)

Body Parameters

Parameter	Type	Required	Description
`description`	string	Required	What was decided
`type`	string	Optional	ROUTINE, ESCALATION, OVERRIDE (default: ROUTINE)
`agent_id`	string	Optional	Agent that made/requested the decision
`reason`	string	Optional	Rationale
`impact`	string	Optional	LOW, MEDIUM, HIGH, CRITICAL (default: LOW)
`decision`	string	Optional	APPROVED, REJECTED, DEFERRED (default: APPROVED)
`approved_by`	string	Optional	Who approved
`confidence`	number	Optional	Confidence 0-1 (default: 0.8)
`provenance`	string	Optional	Data source / evidence
`rollback_plan`	string	Optional	How to undo if needed

GET /api/mission-decisions

List mission-scoped decisions with agent details. Filter by mission_id.

Requires x-konsult-secret or Bearer JWT

Query Parameters

Parameter	Type	Required	Description
`mission_id`	integer	Optional	Filter by mission
`limit`	integer	Optional	Max results (default: 50, max: 200)

POST /api/mission-decisions

Log a mission-specific decision. Supports source-of-truth tracking and override attribution.

Requires x-konsult-secret (admin)

Body Parameters

Parameter	Type	Required	Description
`decision`	string	Required	The decision text
`agent_id`	integer	Optional	Agent (numeric ID)
`mission_id`	integer	Optional	Associated mission
`reason`	string	Optional	Rationale
`source_of_truth`	string	Optional	Evidence source
`overridden_by`	string	Optional	If overriding a previous decision, who authorized

Alerts

System alerts for monitoring. Three severity levels: info, warn, critical. Alerts persist until explicitly resolved.

GET /api/alerts

List alerts. By default returns only unresolved alerts. Pass all=true to include resolved.

Requires x-konsult-secret or Bearer JWT

Query Parameters

Parameter	Type	Required	Description
`all`	string	Optional	Set to "true" to include resolved alerts
`limit`	integer	Optional	Max results (default: 50, max: 200)

Response 200
{
  "ok": true,
  "alerts": [
    {
      "id": 1,
      "level": "critical",
      "source": "K02",
      "message": "Database connection pool exhausted",
      "resolved": false,
      "created_at": "2026-03-22T09:45:00.000Z"
    }
  ]
}

POST /api/alerts

Create a new alert. Invalid levels default to "info".

Requires x-konsult-secret (admin)

Body Parameters

Parameter	Type	Required	Description
`message`	string	Required	Alert message (max 2000 chars)
`level`	string	Optional	info, warn, critical (default: info)
`source`	string	Optional	Source system or agent

Request
curl -X POST \
     -H "x-konsult-secret: YOUR_SECRET" \
     -H "Content-Type: application/json" \
     -d '{"level":"warn","source":"SENT-001","message":"Unusual login pattern detected"}' \
     https://k0nsult.fly.dev/api/alerts

PATCH /api/alerts/:id/resolve

Mark an alert as resolved.

Requires x-konsult-secret (admin)

URL Parameters

Parameter	Type	Required	Description
`id`	integer	Required	Alert ID

Response 200
{
  "ok": true,
  "alert": { "id": 1, "resolved": true }
}

Entry Control

Intake and classification system for new entities entering the K0nsult network. Implements Playbook 1 (Entry Control).

POST /api/entry

Submit a new entity for intake processing. K02 classifies risk, makes accept/hold/probation decision, and optionally auto-registers the agent.

Requires x-konsult-secret (admin)

Body Parameters

Parameter	Type	Required	Description
`entity_type`	string	Required	Type: sentinel, analyst, operator, governor, etc.
`handle`	string	Required	Unique identifier for the entity
`domain`	string	Optional	Domain of operation
`zone`	string	Optional	Zone assignment
`entry_mode`	string	Optional	ENTRY, STOP, BLOCK, QUESTION, ESCALATION, UPDATE
`source_of_truth`	string	Optional	Reference for verification (required to avoid HOLD)
`confidence`	number	Optional	Confidence 0-1 (below 0.3 triggers HOLD)

Response 200
{
  "ok": true,
  "id": 15,
  "decision": "PROBATION",
  "reason": "New entity, probation required",
  "risk_class": "LOW",
  "assigned_level": "P1",
  "assigned_class": "sentinel",
  "next_checkpoint": "F1 Identification -> F2 Classification"
}

GET /api/entry/log

View the entry processing log. Shows all intake decisions.

Requires x-konsult-secret or Bearer JWT

Query Parameters

Parameter	Type	Required	Description
`limit`	integer	Optional	Max results (default: 50, max: 200)

Skills

Skill graph system. Skills have categories, level requirements, and dependencies. Agents earn skills as they progress through ERA stages.

GET /api/skills

List all registered skills, sorted by category and name.

Requires x-konsult-secret or Bearer JWT

Response 200
{
  "ok": true,
  "skills": [
    {
      "skill_id": "ops:multi-task",
      "name": "Multi-task routing",
      "category": "ops",
      "level_required": "E3",
      "description": "Route multiple tasks in parallel"
    }
  ]
}

POST /api/skills

Requires x-konsult-secret (admin)

Body Parameters

Parameter	Type	Required	Description
`skill_id`	string	Required	Unique skill ID (e.g. "ops:multi-task")
`name`	string	Required	Skill display name
`category`	string	Required	Category: info, ops, command, auth, meta
`level_required`	string	Optional	Minimum ERA stage E0-E5 (default: E2)
`description`	string	Optional	Skill description

POST /api/skills/grant

Grant a skill to an agent. Validates ERA stage requirement and checks prerequisite skill dependencies. Creates audit entry.

Requires x-konsult-secret (admin)

Body Parameters

Parameter	Type	Required	Description
`agent_id`	string	Required	Agent ID string
`skill_id`	string	Required	Skill ID to grant
`granted_by`	string	Optional	Who grants (default: K02)

Response 200
{
  "ok": true,
  "granted": true
}

Error 403 — Insufficient Stage
{
  "ok": false,
  "error": "Agent at E1, skill requires E3"
}

Error 400 — Missing Prerequisites
{
  "ok": false,
  "error": "Missing prerequisite skills: ops:multi-task, info:audit-trail"
}

GET /api/skills/agent/:agentId

List all active (non-revoked) skills for a specific agent, with grant details.

Requires x-konsult-secret or Bearer JWT

Response 200
{
  "ok": true,
  "skills": [
    {
      "skill_id": "info:full-reports",
      "name": "Full reports access",
      "category": "info",
      "granted_at": "2026-03-15T12:00:00.000Z",
      "granted_by": "K02"
    }
  ]
}

Audit Trail

Immutable log of all system actions. Every mutation (agent registration, task transition, skill grant, violation, etc.) is recorded.

GET /api/audit

Query the audit trail. Filter by agent_id to see a specific agent's history.

Requires x-konsult-secret or Bearer JWT

Query Parameters

Parameter	Type	Required	Description
`agent_id`	string	Optional	Filter by agent
`limit`	integer	Optional	Max results (default: 50, max: 200)

Response 200
{
  "ok": true,
  "audit": [
    {
      "id": 1,
      "action": "AGENT_REGISTERED",
      "agent_id": "SENT-042",
      "target_type": "agent",
      "target_id": "SENT-042",
      "details": null,
      "performed_by": "system",
      "created_at": "2026-03-22T10:00:00.000Z"
    }
  ]
}

Architecture · Services · Dashboard