​
List Agents

Get all agents in your organization. 
GET /api/agents

​
Authentication

​
Authorization
string
required
Bearer token (JWT) from /auth/login

​
Response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "customer-support-bot",
    "description": "Handles customer support requests",
    "status": "active",
    "created_at": "2024-02-21T10:30:00Z",
    "created_by": "user_123"
  }
]

​
Create Agent

Create a new agent. 
POST /api/agents

​
Request Body

​
name
string
required
Agent name (use kebab-case, e.g., “customer-support-bot”)
​
description
string
Description of what the agent does

​
Example Request

curl -X POST https://api.agentwarden.io/api/agents \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "customer-support-bot",
    "description": "Handles customer support and refunds"
  }'

​
Response

Status: 201 Created 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "customer-support-bot",
  "description": "Handles customer support and refunds",
  "status": "active",
  "created_at": "2024-02-21T10:30:00Z",
  "created_by": "user_123"
}

​
Errors

403 Forbidden - Plan limit exceeded 
{
  "detail": {
    "error": "plan_limit_exceeded",
    "message": "Agent limit reached (2/2). Upgrade your plan to create more agents.",
    "limit_type": "agents",
    "current_plan": "free",
    "upgrade_url": "/settings?tab=plans"
  }
}

​
Get Agent

Get details of a specific agent. 
GET /api/agents/{agent_id}

​
Path Parameters

​
agent_id
string
required
The agent’s unique ID

​
Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "customer-support-bot",
  "description": "Handles customer support and refunds",
  "status": "active",
  "created_at": "2024-02-21T10:30:00Z",
  "created_by": "user_123"
}

​
Errors

404 Not Found 
{
  "detail": "Agent not found"
}

​
Update Agent

Update an agent’s details. 
PUT /api/agents/{agent_id}

​
Request Body

​
name
string
New agent name
​
description
string
New description
​
status
string
Status: “active” or “inactive”

​
Example Request

curl -X PUT https://api.agentwarden.io/api/agents/550e8400... \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description",
    "status": "inactive"
  }'

​
Delete Agent

Delete an agent permanently. 
DELETE /api/agents/{agent_id}

​
Response

Status: 204 No Content
Deleting an agent is permanent and cannot be undone. All permissions will be deleted. Historical logs are preserved.

​
List Agent Permissions

Get all permissions for a specific agent. 
GET /api/agents/{agent_id}/permissions

​
Response

[
  {
    "id": "perm_123",
    "agent_id": "550e8400-e29b-41d4-a716-446655440000",
    "action": "stripe.refund",
    "requires_approval": false,
    "max_amount": 100.00,
    "created_at": "2024-02-21T10:30:00Z"
  }
]

​
Create Permission

Add a permission to an agent. 
POST /api/agents/{agent_id}/permissions

​
Request Body

​
action
string
required
Action identifier (e.g., “stripe.refund”)
​
requires_approval
boolean
default:"false"
Whether this action requires human approval
​
max_amount
float
Maximum monetary amount allowed

​
Example Request

curl -X POST https://api.agentwarden.io/api/agents/550e8400.../permissions \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "stripe.refund",
    "max_amount": 100.00,
    "requires_approval": false
  }'

​
Response

Status: 201 Created 
{
  "id": "perm_123",
  "agent_id": "550e8400-e29b-41d4-a716-446655440000",
  "action": "stripe.refund",
  "requires_approval": false,
  "max_amount": 100.00,
  "created_at": "2024-02-21T10:30:00Z"
}

​
Errors

400 Bad Request - Permission already exists 
{
  "detail": "Permission already exists for this action"
}

​
Delete Permission

Remove a permission from an agent. 
DELETE /api/agents/{agent_id}/permissions/{permission_id}

​
Response

Status: 204 No Content
The agent will immediately be unable to perform this action.