> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deductive.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Complete API reference for integrating with Deductive AI programmatically.

# 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:

```bash theme={null}
curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.deductive.ai/v1/query
```

### Getting Your API Key

1. Sign in to [Deductive AI](https://app.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**:

```json theme={null}
{
  "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**:

```json theme={null}
{
  "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**:

```json theme={null}
{
  "integrations": [
    {
      "id": "github_123",
      "type": "github",
      "status": "connected",
      "connected_at": "2024-01-10T10:00:00Z"
    }
  ]
}
```

#### Create Integration

**Endpoint**: `POST /integrations`

**Request Body**:

```json theme={null}
{
  "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**:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

```python theme={null}
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

```javascript theme={null}
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**:

```json theme={null}
{
  "url": "https://your-app.com/webhooks/deductive",
  "events": ["incident.created", "incident.resolved"],
  "secret": "your-webhook-secret"
}
```

## Next Steps

* [Get Started](/users/welcome) - Set up your first integration
* [Security](/resources/security) - Learn about API security
* [Examples](https://github.com/deductive-ai/examples) - Code examples