​
Overview

The AgentWarden API provides direct HTTP access to all platform features. While we recommend using the Python SDK for most use cases, the API allows you to:
  • Integrate from any programming language
  • Build custom integrations
  • Implement advanced workflows
  • Use AgentWarden from serverless functions

​
Base URL

https://api.agentwarden.io

​
Authentication

AgentWarden uses two authentication methods depending on the endpoint:

​
SDK Endpoints (X-API-Key)

For permission checks and logging (the core SDK functionality): 
curl https://api.agentwarden.io/sdk/check \
  -H "X-API-Key: ak_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "bot", "action": "test", "context": {}}'
​
X-API-Key
string
required
Your organization’s API key from the dashboard

​
Management Endpoints (JWT Bearer Token)

For managing agents, permissions, and viewing logs: 
curl https://api.agentwarden.io/api/agents \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json"
​
Authorization
string
required
Bearer token obtained from /auth/login endpoint

​
Rate Limits

API requests are rate limited based on your plan:
PlanSDK EndpointsManagement Endpoints
Free100/min60/min
Pro1,000/min300/min
Business10,000/min1,000/min
EnterpriseCustomCustom
Rate limit information is included in response headers: 
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640000000

​
Response Format

All API responses use JSON format:

​
Success Response

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

​
Error Response

{
  "detail": "Agent not found"
}
Or for validation errors: 
{
  "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"
  }
}

​
HTTP Status Codes

CodeMeaning
200Success
201Created
204No Content (successful deletion)
400Bad Request (invalid parameters)
401Unauthorized (invalid/missing auth)
403Forbidden (plan limit exceeded)
404Not Found
429Too Many Requests (rate limited)
500Internal Server Error

​
Pagination

List endpoints support pagination: 
curl "https://api.agentwarden.io/api/logs?limit=50&offset=0" \
  -H "Authorization: Bearer YOUR_TOKEN"
​
limit
integer
default:"20"
Number of results per page (max 100)
​
offset
integer
default:"0"
Number of results to skip
Response includes pagination metadata: 
{
  "data": [...],
  "pagination": {
    "total": 250,
    "limit": 50,
    "offset": 0,
    "has_more": true
  }
}

​
Filtering

Many endpoints support filtering: 
curl "https://api.agentwarden.io/api/logs?agent_id=bot-123&status=success" \
  -H "Authorization: Bearer YOUR_TOKEN"
Common filter parameters:
  • agent_id - Filter by specific agent
  • action - Filter by action name
  • status - Filter by status (success, failed, denied, pending)
  • created_after - Filter by creation date (ISO 8601)
  • created_before - Filter by creation date (ISO 8601)

​
Timestamps

All timestamps are in ISO 8601 format with UTC timezone: 
2024-02-21T10:30:00Z

​
Idempotency

For safety, some endpoints support idempotency keys: 
curl -X POST https://api.agentwarden.io/sdk/log \
  -H "X-API-Key: YOUR_KEY" \
  -H "Idempotency-Key: unique-key-123" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "bot", "action": "test", "status": "success"}'
If you retry the same request with the same idempotency key, you’ll get the same response without creating a duplicate.

​
CORS

The API supports CORS for browser-based applications: 
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type, X-API-Key
Never expose your API key in client-side code. Use a backend proxy to make API calls.

​
Webhooks

AgentWarden can send webhooks for various events:
  • approval.approved - When an approval is granted
  • approval.denied - When an approval is denied
  • agent.created - When a new agent is created
  • permission.updated - When permissions change
Configure webhooks in your dashboard under Settings → Webhooks.

​
SDKs and Libraries

Official SDKs:

Python

Official Python SDK

JavaScript

Coming soon

Go

Coming soon

Ruby

Coming soon

​
API Endpoints

Check Permission

Check if an agent can perform an action

Log Action

Log an agent action for audit trail

Manage Agents

Create and manage agents

Manage Permissions

Configure agent permissions

​
Support

Need help with the API?

Discord Community

Chat with the community

Email Support

Contact our support team

GitHub Issues

Report bugs or request features

Status Page

Check API status