docs/API_SPECIFICATION.md

# API Specification - BDR Agent Factory

## Overview

The BDR Agent Factory provides a RESTful API for accessing AI capabilities, managing governance, and integrating with insurance business systems.

**Base URL**: `https://api.bdragentfactory.com/v1`

**Authentication**: Bearer token (OAuth 2.0)

---

## Authentication

### Obtain Access Token

```http
POST /auth/token
Content-Type: application/json

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "grant_type": "client_credentials"
}
```

**Response**:
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}
```

---

## Core Endpoints

### 1. Capabilities

#### List All Capabilities

```http
GET /capabilities
Authorization: Bearer {access_token}
```

**Query Parameters**:
- `category` (optional): Filter by category (generation, transformation, language, etc.)
- `domain` (optional): Filter by domain (claims, underwriting, etc.)
- `explainable` (optional): Filter by explainability (true/false)
- `page` (optional): Page number (default: 1)
- `limit` (optional): Items per page (default: 20, max: 100)

**Response**:
```json
{
  "data": [
    {
      "id": "cap_text_classification",
      "name": "Text Classification",
      "category": "language",
      "description": "Categorize text into predefined classes",
      "supported_domains": ["claims", "underwriting", "customer_service"],
      "insurance_use_cases": [
        "Claim type classification",
        "Policy document categorization"
      ],
      "decision_types": ["approve", "review", "reject"],
      "explainable": true,
      "auditable": true,
      "version": "1.0.0",
      "status": "production"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 50,
    "total_pages": 3
  }
}
```

#### Get Capability Details

```http
GET /capabilities/{capability_id}
Authorization: Bearer {access_token}
```

**Response**:
```json
{
  "id": "cap_text_classification",
  "name": "Text Classification",
  "category": "language",
  "description": "Categorize text into predefined classes",
  "supported_domains": ["claims", "underwriting", "customer_service"],
  "insurance_use_cases": [
    "Claim type classification",
    "Policy document categorization"
  ],
  "decision_types": ["approve", "review", "reject"],
  "explainable": true,
  "auditable": true,
  "version": "1.0.0",
  "status": "production",
  "endpoints": {
    "invoke": "/capabilities/cap_text_classification/invoke",
    "batch": "/capabilities/cap_text_classification/batch"
  },
  "input_schema": {
    "type": "object",
    "properties": {
      "text": {"type": "string", "required": true},
      "classes": {"type": "array", "items": {"type": "string"}},
      "confidence_threshold": {"type": "number", "default": 0.7}
    }
  },
  "output_schema": {
    "type": "object",
    "properties": {
      "predicted_class": {"type": "string"},
      "confidence": {"type": "number"},
      "all_scores": {"type": "object"},
      "explanation": {"type": "object"}
    }
  },
  "performance_metrics": {
    "avg_latency_ms": 150,
    "p95_latency_ms": 300,
    "accuracy": 0.94,
    "throughput_rps": 100
  }
}
```

#### Invoke Capability

```http
POST /capabilities/{capability_id}/invoke
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "input": {
    "text": "Customer reported water damage to basement after heavy rain",
    "classes": ["property_damage", "auto_accident", "health_claim", "liability"],
    "confidence_threshold": 0.8
  },
  "options": {
    "explain": true,
    "audit_trail": true,
    "request_id": "req_12345"
  }
}
```

**Response**:
```json
{
  "request_id": "req_12345",
  "capability_id": "cap_text_classification",
  "timestamp": "2026-01-03T00:13:00Z",
  "result": {
    "predicted_class": "property_damage",
    "confidence": 0.96,
    "all_scores": {
      "property_damage": 0.96,
      "liability": 0.03,
      "auto_accident": 0.01,
      "health_claim": 0.00
    },
    "explanation": {
      "method": "SHAP",
      "key_features": [
        {"feature": "water damage", "importance": 0.45},
        {"feature": "basement", "importance": 0.32},
        {"feature": "heavy rain", "importance": 0.18}
      ]
    }
  },
  "metadata": {
    "model_version": "1.0.0",
    "processing_time_ms": 142,
    "compliance_flags": {
      "explainable": true,
      "auditable": true,
      "gdpr_compliant": true
    }
  },
  "audit_trail": {
    "audit_id": "audit_67890",
    "stored": true,
    "retention_days": 2555
  }
}
```

#### Batch Invoke

```http
POST /capabilities/{capability_id}/batch
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "inputs": [
    {"text": "First claim description"},
    {"text": "Second claim description"},
    {"text": "Third claim description"}
  ],
  "options": {
    "explain": false,
    "batch_id": "batch_12345"
  }
}
```

**Response**:
```json
{
  "batch_id": "batch_12345",
  "status": "processing",
  "total_items": 3,
  "estimated_completion": "2026-01-03T00:15:00Z",
  "status_url": "/batch/batch_12345/status",
  "results_url": "/batch/batch_12345/results"
}
```

---

### 2. Systems

#### List Business Systems

```http
GET /systems
Authorization: Bearer {access_token}
```

**Response**:
```json
{
  "data": [
    {
      "id": "sys_claims_gpt",
      "name": "ClaimsGPT",
      "description": "AI-powered claims decision intelligence",
      "status": "production",
      "capabilities": [
        "cap_text_classification",
        "cap_sentiment_analysis",
        "cap_fraud_detection"
      ],
      "compliance_requirements": ["IFRS17", "GDPR"],
      "version": "2.1.0"
    }
  ]
}
```

#### Get System Details

```http
GET /systems/{system_id}
Authorization: Bearer {access_token}
```

#### Register New System

```http
POST /systems
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "name": "NewInsuranceAgent",
  "description": "Description of the new system",
  "required_capabilities": ["cap_text_classification"],
  "compliance_requirements": ["GDPR"],
  "owner": "team@company.com"
}
```

---

### 3. Governance & Audit

#### Get Audit Trail

```http
GET /audit/trail
Authorization: Bearer {access_token}
```

**Query Parameters**:
- `capability_id` (optional): Filter by capability
- `system_id` (optional): Filter by system
- `start_date` (required): ISO 8601 date
- `end_date` (required): ISO 8601 date
- `decision_type` (optional): Filter by decision type

**Response**:
```json
{
  "data": [
    {
      "audit_id": "audit_67890",
      "timestamp": "2026-01-03T00:13:00Z",
      "capability_id": "cap_text_classification",
      "system_id": "sys_claims_gpt",
      "request_id": "req_12345",
      "user_id": "user_123",
      "input_hash": "sha256:abc123...",
      "output_hash": "sha256:def456...",
      "decision_type": "approve",
      "confidence": 0.96,
      "compliance_flags": {
        "explainable": true,
        "auditable": true,
        "gdpr_compliant": true
      },
      "retention_until": "2033-01-03T00:13:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1000
  }
}
```

#### Get Compliance Report

```http
GET /governance/compliance-report
Authorization: Bearer {access_token}
```

**Query Parameters**:
- `framework` (required): IFRS17, HIPAA, GDPR, or AML
- `start_date` (required): ISO 8601 date
- `end_date` (required): ISO 8601 date

**Response**:
```json
{
  "framework": "GDPR",
  "period": {
    "start": "2026-01-01T00:00:00Z",
    "end": "2026-01-03T23:59:59Z"
  },
  "summary": {
    "total_requests": 10000,
    "compliant_requests": 9998,
    "compliance_rate": 0.9998,
    "violations": 2
  },
  "metrics": {
    "data_retention_compliance": 1.0,
    "right_to_explanation": 1.0,
    "consent_tracking": 0.9998,
    "data_minimization": 1.0
  },
  "violations": [
    {
      "violation_id": "viol_001",
      "timestamp": "2026-01-02T14:30:00Z",
      "type": "missing_consent",
      "severity": "medium",
      "remediation_status": "resolved"
    }
  ]
}
```

#### Get Explainability Report

```http
GET /governance/explainability/{request_id}
Authorization: Bearer {access_token}
```

**Response**:
```json
{
  "request_id": "req_12345",
  "capability_id": "cap_text_classification",
  "timestamp": "2026-01-03T00:13:00Z",
  "explanation": {
    "method": "SHAP",
    "global_explanation": {
      "model_type": "transformer",
      "training_data_size": 100000,
      "feature_importance": [
        {"feature": "claim_keywords", "importance": 0.45},
        {"feature": "context_words", "importance": 0.35},
        {"feature": "sentence_structure", "importance": 0.20}
      ]
    },
    "local_explanation": {
      "input_text": "Customer reported water damage to basement after heavy rain",
      "prediction": "property_damage",
      "confidence": 0.96,
      "key_features": [
        {"feature": "water damage", "importance": 0.45, "contribution": "+0.43"},
        {"feature": "basement", "importance": 0.32, "contribution": "+0.31"},
        {"feature": "heavy rain", "importance": 0.18, "contribution": "+0.17"}
      ],
      "counterfactual": "If 'water damage' was replaced with 'minor scratch', prediction would be 'auto_accident' with 0.82 confidence"
    }
  },
  "human_readable_summary": "The model classified this as property damage with 96% confidence primarily because of the keywords 'water damage' (45% importance), 'basement' (32% importance), and 'heavy rain' (18% importance). These terms are strongly associated with property damage claims in the training data."
}
```

---

### 4. Monitoring & Metrics

#### Get System Health

```http
GET /monitoring/health
Authorization: Bearer {access_token}
```

**Response**:
```json
{
  "status": "healthy",
  "timestamp": "2026-01-03T00:13:00Z",
  "services": {
    "api": {"status": "up", "latency_ms": 12},
    "database": {"status": "up", "latency_ms": 8},
    "ml_inference": {"status": "up", "latency_ms": 145},
    "audit_service": {"status": "up", "latency_ms": 23}
  },
  "uptime_percentage": 99.97
}
```

#### Get Performance Metrics

```http
GET /monitoring/metrics
Authorization: Bearer {access_token}
```

**Query Parameters**:
- `capability_id` (optional): Filter by capability
- `time_range` (optional): 1h, 24h, 7d, 30d (default: 24h)

**Response**:
```json
{
  "time_range": "24h",
  "metrics": {
    "total_requests": 50000,
    "successful_requests": 49950,
    "failed_requests": 50,
    "success_rate": 0.999,
    "avg_latency_ms": 152,
    "p50_latency_ms": 140,
    "p95_latency_ms": 280,
    "p99_latency_ms": 450,
    "throughput_rps": 0.58,
    "error_rate": 0.001
  },
  "by_capability": [
    {
      "capability_id": "cap_text_classification",
      "requests": 15000,
      "avg_latency_ms": 142,
      "success_rate": 0.999
    }
  ]
}
```

---

## Error Handling

### Error Response Format

```json
{
  "error": {
    "code": "INVALID_INPUT",
    "message": "The input text exceeds maximum length of 10000 characters",
    "details": {
      "field": "text",
      "provided_length": 15000,
      "max_length": 10000
    },
    "request_id": "req_12345",
    "timestamp": "2026-01-03T00:13:00Z"
  }
}
```

### Error Codes

| Code | HTTP Status | Description |
|------|-------------|-------------|
| `AUTHENTICATION_FAILED` | 401 | Invalid or expired access token |
| `AUTHORIZATION_FAILED` | 403 | Insufficient permissions |
| `INVALID_INPUT` | 400 | Input validation failed |
| `CAPABILITY_NOT_FOUND` | 404 | Capability ID does not exist |
| `SYSTEM_NOT_FOUND` | 404 | System ID does not exist |
| `RATE_LIMIT_EXCEEDED` | 429 | Too many requests |
| `INTERNAL_ERROR` | 500 | Internal server error |
| `SERVICE_UNAVAILABLE` | 503 | Service temporarily unavailable |
| `COMPLIANCE_VIOLATION` | 422 | Request violates compliance rules |

---

## Rate Limiting

- **Standard Tier**: 100 requests/minute, 10,000 requests/day
- **Premium Tier**: 1,000 requests/minute, 100,000 requests/day
- **Enterprise Tier**: Custom limits

**Rate Limit Headers**:
```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1704240000
```

---

## Versioning

API versions are specified in the URL path:
- Current: `/v1`
- Beta: `/v2-beta`

Version deprecation notices are provided 6 months in advance.

---

## SDKs

### Python
```python
from bdr_agent_factory import Client

client = Client(api_key="your_api_key")

result = client.capabilities.invoke(
    capability_id="cap_text_classification",
    input={"text": "Claim description"},
    options={"explain": True}
)

print(result.predicted_class)
print(result.explanation)
```

### JavaScript/TypeScript
```javascript
import { BDRAgentFactory } from '@bdr/agent-factory';

const client = new BDRAgentFactory({ apiKey: 'your_api_key' });

const result = await client.capabilities.invoke({
  capabilityId: 'cap_text_classification',
  input: { text: 'Claim description' },
  options: { explain: true }
});

console.log(result.predictedClass);
```

---

## Webhooks

### Register Webhook

```http
POST /webhooks
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "url": "https://your-domain.com/webhook",
  "events": ["capability.invoked", "compliance.violation"],
  "secret": "your_webhook_secret"
}
```

### Webhook Events

- `capability.invoked` - Capability was invoked
- `capability.failed` - Capability invocation failed
- `compliance.violation` - Compliance violation detected
- `audit.created` - New audit trail entry created
- `system.registered` - New system registered

---

## Support

For API support:
- Email: api-support@bdragentfactory.com
- Documentation: https://docs.bdragentfactory.com
- Status Page: https://status.bdragentfactory.com