Skip to main content

​
API Reference

Deductive AI provides a comprehensive REST API for programmatic access to all platform features.

​
Authentication

​
API Keys

All API requests require authentication using an API key: 
curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.deductive.ai/v1/query

​
Getting Your API Key

  1. Sign in to Deductive AI
  2. Navigate to Settings > API Keys
  3. Click Create API Key
  4. Copy and store your API key securely
Note: API keys are only shown once. Store them securely.

​
Key Types

  • Admin Keys - Full access to all resources
  • Assistant Keys - Limited access for assistant API only

​
Base URL

All API requests should be made to: 
https://api.deductive.ai/v1

​
Rate Limits

  • Standard: 100 requests per minute
  • Enterprise: 1000 requests per minute
Rate limit headers are included in all responses: 
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

​
Endpoints

​
Query

Submit a natural language query to Deductive AI. Endpoint: POST /query Request Body: 
{
  "query": "What caused the error spike at 3pm?",
  "context": {
    "service": "payment-service",
    "time_range": {
      "start": "2024-01-15T15:00:00Z",
      "end": "2024-01-15T16:00:00Z"
    }
  }
}
Response: 
{
  "id": "query_123",
  "answer": "The error spike was caused by...",
  "evidence": [
    {
      "source": "logs",
      "type": "error",
      "content": "..."
    }
  ],
  "confidence": 0.95,
  "timestamp": "2024-01-15T16:00:00Z"
}

​
Integrations

​
List Integrations

Endpoint: GET /integrations Response: 
{
  "integrations": [
    {
      "id": "github_123",
      "type": "github",
      "status": "connected",
      "connected_at": "2024-01-10T10:00:00Z"
    }
  ]
}

​
Create Integration

Endpoint: POST /integrations Request Body: 
{
  "type": "github",
  "config": {
    "app_id": "12345",
    "client_id": "abc123",
    "client_secret": "secret456"
  }
}

​
Incidents

​
List Incidents

Endpoint: GET /incidents Query Parameters:
  • status - Filter by status (open, resolved, investigating)
  • severity - Filter by severity (low, medium, high, critical)
  • start_time - Filter incidents after this time
  • end_time - Filter incidents before this time

​
Get Incident

Endpoint: GET /incidents/{id} Response: 
{
  "id": "incident_123",
  "title": "Payment Service Errors",
  "status": "investigating",
  "severity": "high",
  "created_at": "2024-01-15T15:00:00Z",
  "root_cause": {
    "summary": "Database connection pool exhausted",
    "confidence": 0.92,
    "evidence": [...]
  }
}

​
Error Handling

All errors follow a consistent format: 
{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The request is invalid",
    "details": {
      "field": "query",
      "reason": "Query cannot be empty"
    }
  }
}

​
Error Codes

  • INVALID_REQUEST - Request validation failed
  • UNAUTHORIZED - Authentication required
  • FORBIDDEN - Insufficient permissions
  • NOT_FOUND - Resource not found
  • RATE_LIMIT_EXCEEDED - Too many requests
  • INTERNAL_ERROR - Server error

​
SDKs

​
Python

from deductive import DeductiveClient

client = DeductiveClient(api_key="YOUR_API_KEY")

response = client.query(
    "What caused the error spike?",
    context={"service": "payment-service"}
)

print(response.answer)

​
JavaScript

const { DeductiveClient } = require('@deductive/ai');

const client = new DeductiveClient({
  apiKey: 'YOUR_API_KEY'
});

const response = await client.query(
  'What caused the error spike?',
  { context: { service: 'payment-service' } }
);

console.log(response.answer);

​
Webhooks

Subscribe to events for real-time updates: Endpoint: POST /webhooks Request Body: 
{
  "url": "https://your-app.com/webhooks/deductive",
  "events": ["incident.created", "incident.resolved"],
  "secret": "your-webhook-secret"
}

​
Next Steps