API_DOCS.md

# vBot API Documentation

## Overview

The vBot API provides endpoints for call processing and customer management. All API requests require authentication using an API key.

## Authentication

All API requests must include your API key in the `X-API-Key` header:

```bash
curl -X POST https://vbot-server.com/api/process-call \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@/path/to/call.wav"
```

## Endpoints

### Call Processing

#### Process Call
```http
POST /api/process-call
```

Process a call recording and receive analysis results via webhook.

**Headers:**
- `X-API-Key`: Your API key
- `Content-Type`: multipart/form-data

**Parameters:**
- `file`: Call recording file (WAV format)
- `caller_number`: Caller's phone number
- `called_number`: Called phone number

**Response:**
```json
{
  "status": "success",
  "message": "Call processing started",
  "call_id": "uuid"
}
```

**Webhook Payload:**
```json
{
  "call_id": "uuid",
  "caller_number": "+1234567890",
  "called_number": "+0987654321",
  "transcription": "Call transcript...",
  "summary": "Call summary...",
  "sentiment": "positive",
  "keywords": "keyword1, keyword2",
  "timestamp": "2024-03-14T12:00:00Z",
  "customer_id": 123
}
```

### Customer Management

#### List Customers (Admin Only)
```http
GET /api/customers
```

List all customers.

**Headers:**
- `Authorization`: Bearer token (admin only)

**Response:**
```json
{
  "customers": [
    {
      "id": 1,
      "name": "Customer Name",
      "company_name": "Company Name",
      "email": "customer@example.com",
      "api_key": "api_key_here",
      "is_active": true,
      "created_at": "2024-03-14T12:00:00Z",
      "updated_at": "2024-03-14T12:00:00Z"
    }
  ]
}
```

#### Create Customer (Admin Only)
```http
POST /api/customers
```

Create a new customer.

**Headers:**
- `Authorization`: Bearer token (admin only)
- `Content-Type`: application/json

**Request Body:**
```json
{
  "name": "Customer Name",
  "company_name": "Company Name",
  "email": "customer@example.com"
}
```

**Response:**
```json
{
  "id": 1,
  "name": "Customer Name",
  "company_name": "Company Name",
  "email": "customer@example.com",
  "api_key": "generated_api_key",
  "is_active": true,
  "created_at": "2024-03-14T12:00:00Z",
  "updated_at": "2024-03-14T12:00:00Z"
}
```

#### Update Customer (Admin Only)
```http
PUT /api/customers/{customer_id}
```

Update customer details.

**Headers:**
- `Authorization`: Bearer token (admin only)
- `Content-Type`: application/json

**Request Body:**
```json
{
  "name": "Updated Name",
  "company_name": "Updated Company",
  "email": "updated@example.com",
  "is_active": true
}
```

**Response:**
```json
{
  "id": 1,
  "name": "Updated Name",
  "company_name": "Updated Company",
  "email": "updated@example.com",
  "api_key": "existing_api_key",
  "is_active": true,
  "created_at": "2024-03-14T12:00:00Z",
  "updated_at": "2024-03-14T12:00:00Z"
}
```

#### Delete Customer (Admin Only)
```http
DELETE /api/customers/{customer_id}
```

Delete a customer.

**Headers:**
- `Authorization`: Bearer token (admin only)

**Response:**
```json
{
  "status": "success",
  "message": "Customer deleted successfully"
}
```

### Health Check

#### Check API Health
```http
GET /health
```

Check API health status.

**Response:**
```json
{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2024-03-14T12:00:00Z"
}
```

## Error Responses

All endpoints may return the following error responses:

### 401 Unauthorized
```json
{
  "status": "error",
  "message": "Invalid API key"
}
```

### 403 Forbidden
```json
{
  "status": "error",
  "message": "Insufficient permissions"
}
```

### 404 Not Found
```json
{
  "status": "error",
  "message": "Resource not found"
}
```

### 400 Bad Request
```json
{
  "status": "error",
  "message": "Invalid request parameters"
}
```

### 500 Internal Server Error
```json
{
  "status": "error",
  "message": "Internal server error"
}
```

## Rate Limits

- API requests are limited to 100 requests per minute per API key
- Webhook delivery attempts are limited to 3 retries
- Call processing is limited to 10 concurrent calls per customer

## Best Practices

1. Always use HTTPS for API requests
2. Store API keys securely
3. Implement webhook retry logic
4. Monitor API usage and rate limits
5. Keep API keys confidential
6. Use appropriate error handling
7. Implement request timeouts
8. Monitor webhook delivery status