Endpoint
Triggers an investigation using the specified agent.
Authentication
Requires Team Token or Admin Token.
Request
| Header | Required | Description |
|---|
Authorization | Yes | Bearer YOUR_TOKEN |
Content-Type | Yes | application/json |
Body Parameters
| Parameter | Type | Required | Description |
|---|
agent_name | string | Yes | Agent to invoke |
message | string | Yes | Investigation request |
context | object | No | Additional context |
async | boolean | No | Return immediately (default: false) |
Available Agents
| Agent | Description |
|---|
planner | Orchestrates full investigations |
investigation_agent | Comprehensive troubleshooting |
k8s_agent | Kubernetes-focused |
aws_agent | AWS-focused |
coding_agent | Code analysis |
Request Example
curl -X POST https://api.incidentfox.ai/api/v1/agents/run \
-H "Authorization: Bearer $TEAM_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"agent_name": "planner",
"message": "Investigate high latency in the payments service",
"context": {
"service": "payments",
"environment": "production",
"severity": "high"
}
}'
Response
Success Response (200)
{
"investigation_id": "inv_abc123",
"status": "completed",
"duration_seconds": 45,
"result": {
"summary": "Payment service experiencing elevated latency due to database connection pool exhaustion",
"root_cause": {
"description": "RDS connection pool at maximum capacity (100/100 connections)",
"confidence": 92,
"evidence": [
"CloudWatch RDS connections metric at 100%",
"Application logs show 'connection timeout' errors",
"Spike correlates with deployment at 14:32 UTC"
]
},
"timeline": [
{
"timestamp": "2024-01-15T14:32:00Z",
"event": "New deployment rolled out"
},
{
"timestamp": "2024-01-15T14:35:00Z",
"event": "Connection count started increasing"
},
{
"timestamp": "2024-01-15T14:42:00Z",
"event": "Connection pool exhausted"
}
],
"affected_systems": [
"payments-service",
"checkout-service",
"RDS primary"
],
"recommendations": [
{
"priority": "high",
"action": "Increase RDS max_connections parameter"
},
{
"priority": "medium",
"action": "Review connection pool settings in application config"
},
{
"priority": "low",
"action": "Consider connection pooler like PgBouncer"
}
]
},
"tools_used": [
"get_cloudwatch_logs",
"get_cloudwatch_metrics",
"get_pod_logs",
"search_github_code"
],
"created_at": "2024-01-15T14:45:00Z"
}
Async Response (202)
When async: true:
{
"investigation_id": "inv_abc123",
"status": "running",
"poll_url": "/api/v1/agents/status/inv_abc123",
"created_at": "2024-01-15T14:45:00Z"
}
Error Responses
400 Bad Request
{
"error": {
"code": "invalid_request",
"message": "agent_name is required"
}
}
{
"error": {
"code": "unauthorized",
"message": "Invalid or expired token"
}
}
{
"error": {
"code": "rate_limited",
"message": "Too many investigation requests",
"retry_after": 60
}
}
Async Investigations
For long-running investigations, use async mode:
curl -X POST https://api.incidentfox.ai/api/v1/agents/run \
-H "Authorization: Bearer $TEAM_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"agent_name": "planner",
"message": "Full system health check",
"async": true
}'
curl -X GET https://api.incidentfox.ai/api/v1/agents/status/inv_abc123 \
-H "Authorization: Bearer $TEAM_TOKEN"
Context Parameters
Provide additional context to improve investigation accuracy:
{
"context": {
"service": "payments",
"environment": "production",
"namespace": "checkout",
"severity": "high",
"related_alert": "alert_xyz789",
"time_window": "1h",
"hint": "Check recent deployments"
}
}
| Context Field | Description |
|---|
service | Target service name |
environment | prod, staging, dev |
namespace | Kubernetes namespace |
severity | high, medium, low |
related_alert | Alert ID for context |
time_window | Investigation time range |
hint | Additional guidance |
Code Examples
Python
import requests
response = requests.post(
"https://api.incidentfox.ai/api/v1/agents/run",
headers={
"Authorization": f"Bearer {TEAM_TOKEN}",
"Content-Type": "application/json"
},
json={
"agent_name": "planner",
"message": "Investigate high latency in payments"
}
)
result = response.json()
print(f"Root cause: {result['result']['root_cause']['description']}")
JavaScript
const response = await fetch('https://api.incidentfox.ai/api/v1/agents/run', {
method: 'POST',
headers: {
'Authorization': `Bearer ${TEAM_TOKEN}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
agent_name: 'planner',
message: 'Investigate high latency in payments'
})
});
const result = await response.json();
console.log(`Root cause: ${result.result.root_cause.description}`);
Next Steps
