Agents API

Manage AI agents registered with TheWARDN.

List Agents

GET /agents

Returns all agents for your tenant.

Query Parameters:

Param	Type	Description
status	string	Filter by status: active, paused, blocked, deregistered

Response:

{
  "agents": [
    {
      "id": "agt_abc123",
      "name": "deploy-bot",
      "description": "Automated deployment agent",
      "status": "active",
      "tier_override": null,
      "confidence_floor": 0.85,
      "total_governed": 1247,
      "total_cleared": 1180,
      "total_held": 52,
      "total_blocked": 15,
      "last_seen": "2026-04-10T20:00:00Z",
      "created_at": "2026-03-15T10:00:00Z"
    }
  ],
  "total": 1
}

Register Agent

POST /agents

Register a new AI agent. Requires ARCHITECT role.

Request:

{
  "name": "deploy-bot",
  "description": "Automated deployment agent for CI/CD pipeline"
}

Response:

{
  "id": "agt_abc123",
  "name": "deploy-bot",
  "description": "Automated deployment agent for CI/CD pipeline",
  "status": "active",
  "created_at": "2026-04-10T20:00:00Z"
}

Get Agent

GET /agents/:id

Get details for a specific agent.

Update Agent

PATCH /agents/:id

Update agent properties. Requires ARCHITECT role.

Request:

{
  "description": "Updated description",
  "tier_override": "B",
  "confidence_floor": 0.90
}

Agent Status Management

Pause Agent

POST /agents/:id/pause

Pause an agent. All subsequent actions will be auto-HELD in escrow.

Request:

{
  "reason": "Investigating anomalous behavior pattern"
}

Resume Agent

POST /agents/:id/resume

Resume a paused agent. Returns to normal governance evaluation.

Block Agent

POST /agents/:id/block

Block an agent. All subsequent actions will be auto-BLOCKED with violation records.

Request:

{
  "reason": "Agent violated data handling policy - blocking pending investigation"
}

Unblock Agent

POST /agents/:id/unblock

Remove block from an agent.

Deregister Agent

POST /agents/:id/deregister

Deregister an agent. The agent can no longer submit governance requests.

WARNING

Deregistration is reversible but requires re-registration. All historical governance data is preserved.

Agent Policies

Assign Policy to Agent

POST /agents/:id/policies

Assign a CHAM policy specifically to this agent (in addition to tenant-wide policies).

Request:

{
  "policy_id": "pol_xyz789"
}

List Agent Policies

GET /agents/:id/policies

List all policies assigned to this agent.

Remove Agent Policy

DELETE /agents/:id/policies/:policy_id

Remove a policy assignment from an agent.

Agent Statistics

Get Agent Stats

GET /agents/:id/stats

Get detailed governance statistics for an agent.

{
  "total_governed": 1247,
  "total_cleared": 1180,
  "total_held": 52,
  "total_blocked": 15,
  "clearance_rate": 0.946,
  "most_common_action": "data_query",
  "last_violation": "2026-04-08T15:30:00Z",
  "active_escrow_count": 2
}