Agents API

Register, manage, and discover AI agents.

Register Agent

POST /api/v1/agents

Register a new agent and receive a one-time API key.

Request Body

Field	Type	Required	Description
name	string	Yes	Human-readable name
agent_type	string	Yes	compliance, security, monitoring, remediation, audit
description	string	No	Agent purpose description
capabilities	string[]	No	Authorized MCP tool names
data_classifications	string[]	No	public, internal, confidential, restricted
certificate_fingerprint	string	No	SHA-256 certificate fingerprint for mTLS
metadata	object	No	Arbitrary key-value metadata

Example Request

curl -X POST https://api.clawgrc.com/api/v1/agents \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "compliance-bot",
    "agent_type": "compliance",
    "description": "Automated compliance evidence collector",
    "capabilities": ["grc.list_frameworks", "grc.get_compliance_score"],
    "data_classifications": ["internal"]
  }'

Example Response (201 Created)

{
  "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "api_key": "cgrc_ABCDEFghijklmnopqrstuvwxyz1234567890ABCD"
}

warning

The api_key is returned only once. Store it securely.

---

List Agents

GET /api/v1/agents

List agents for the authenticated organization.

Query Parameters

Parameter	Type	Default	Description
limit	integer	50	Maximum results (1-200)
offset	integer	0	Pagination offset
status	string	-	Filter: active, inactive

Example Response

{
  "agents": [
    {
      "id": "agent-uuid",
      "org_id": "org-uuid",
      "name": "compliance-bot",
      "agent_type": "compliance",
      "capabilities": ["grc.list_frameworks", "grc.get_compliance_score"],
      "data_classifications": ["internal"],
      "trust_score": 0.85,
      "status": "active",
      "description": "Automated compliance evidence collector",
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-15T14:30:00Z"
    }
  ],
  "total": 3,
  "limit": 50,
  "offset": 0
}

---

Get Agent

GET /api/v1/agents/:agent_id

Returns a single agent by ID.

---

Update Agent

PUT /api/v1/agents/:agent_id

Update mutable agent properties.

Request Body

All fields are optional. Only provided fields are updated.

Field	Type	Description
name	string	Updated name
description	string	Updated description
capabilities	string[]	Updated capabilities list
data_classifications	string[]	Updated data classifications
status	string	active or inactive
certificate_fingerprint	string	Updated certificate fingerprint
metadata	object	Updated metadata

Example Request

curl -X PUT https://api.clawgrc.com/api/v1/agents/agent-uuid \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "capabilities": ["grc.list_frameworks", "grc.get_compliance_score", "grc.create_finding"]
  }'

---

Deregister Agent

DELETE /api/v1/agents/:agent_id

Soft-delete an agent by setting status to inactive.

Response (204 No Content)

---

Rotate API Key

POST /api/v1/agents/:agent_id/rotate-key

Generate a new API key, invalidating the old one immediately.

Example Response

{
  "agent_id": "agent-uuid",
  "api_key": "cgrc_NEWKEYxyz..."
}

---

Discover Agents

POST /api/v1/agents/discover

Find agents by capability and trust score within your organization.

Request Body

Field	Type	Required	Description
capabilities	string[]	No	Required capabilities
min_trust_score	number	No	Minimum trust score (0.0-1.0, default: 0.0)
status	string	No	Agent status filter (default: active)
limit	integer	No	Maximum results (default: 50)

Example Request

curl -X POST https://api.clawgrc.com/api/v1/agents/discover \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "capabilities": ["grc.trigger_scan"],
    "min_trust_score": 0.7
  }'

Example Response

{
  "agents": [
    {
      "id": "agent-uuid",
      "name": "security-scanner",
      "agent_type": "security",
      "trust_score": 0.92,
      "capabilities": ["grc.trigger_scan", "grc.create_finding"],
      "status": "active"
    }
  ],
  "total": 1
}

Results are sorted by trust_score descending.

---

Invoke Agent

POST /api/v1/agents/:agent_id/invoke

Invoke another agent on behalf of the caller.

Request Body

Field	Type	Required	Description
method	string	Yes	Method to call on the target agent
params	object	No	Parameters for the method
min_trust_score	number	No	Minimum trust score required (default: 0.0)
required_capability	string	No	Capability the target must have

Example Response (202 Accepted)

{
  "request_id": "req-uuid",
  "source_agent_id": "caller-uuid",
  "target_agent_id": "target-uuid",
  "method": "analyze",
  "status": "queued",
  "duration_ms": 15,
  "interaction_id": "interaction-uuid"
}

Error Responses

Status	Description
403	Trust score too low or calling agent not active
404	Target agent not found
409	Target agent is inactive
422	Target agent lacks required capability