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

# Calls API

> Retrieve and manage emergency call data

## Calls Endpoint

Retrieve and manage emergency call data stored in DynamoDB and S3 for access911.

### Endpoint

```
GET https://your-api-gateway-url/calls
```

### Request

#### Headers

| Header   | Type   | Required | Description        |
| -------- | ------ | -------- | ------------------ |
| `Accept` | string | No       | `application/json` |

#### Query Parameters

| Parameter        | Type    | Required | Default | Description                                |
| ---------------- | ------- | -------- | ------- | ------------------------------------------ |
| `limit`          | integer | No       | `50`    | Maximum number of calls to return (1-1000) |
| `offset`         | integer | No       | `0`     | Number of calls to skip                    |
| `emergency_type` | string  | No       | -       | Filter by emergency type                   |
| `severity`       | string  | No       | -       | Filter by severity level                   |
| `status`         | string  | No       | -       | Filter by call status                      |
| `start_date`     | string  | No       | -       | Start date filter (ISO 8601)               |
| `end_date`       | string  | No       | -       | End date filter (ISO 8601)                 |
| `location`       | string  | No       | -       | Filter by location area                    |
| `simulation`     | boolean | No       | -       | Filter by simulation status                |

### Request Examples

#### Get Recent Calls

```bash theme={null}
curl -X GET "https://your-api-gateway-url/calls?limit=20" \
  -H "Accept: application/json"
```

#### Filter by Emergency Type

```bash theme={null}
curl -X GET "https://your-api-gateway-url/calls?emergency_type=structure_fire&limit=10" \
  -H "Accept: application/json"
```

#### Filter by Severity

```bash theme={null}
curl -X GET "https://your-api-gateway-url/calls?severity=critical&limit=25" \
  -H "Accept: application/json"
```

#### Date Range Filter

```bash theme={null}
curl -X GET "https://your-api-gateway-url/calls?start_date=2023-12-01T00:00:00Z&end_date=2023-12-31T23:59:59Z" \
  -H "Accept: application/json"
```

#### Complex Filter

```bash theme={null}
curl -X GET "https://your-api-gateway-url/calls?emergency_type=structure_fire&severity=critical&status=active&limit=50" \
  -H "Accept: application/json"
```

### Response

#### Success Response

```json theme={null}
{
  "calls": [
    {
      "conversation_id": "conv_123456789",
      "timestamp": 1703123456,
      "agent_id": "agent_emergency_911",
      "summary": "Caller reported house fire and provided location details.",
      "call_successful": true,
      "duration_secs": 180,
      "transcript_length": 15,
      "created_at": "2023-12-21T10:30:56.789Z",
      "emergency_type": "structure_fire",
      "location": "1234 Main Street, Anytown",
      "latitude": 34.0522,
      "longitude": -118.2437,
      "severity": "critical",
      "status": "active",
      "simulation": false,
      "scenario": null,
      "scenario_name": null
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 150,
    "has_more": true
  },
  "filters": {
    "emergency_type": null,
    "severity": null,
    "status": null,
    "start_date": null,
    "end_date": null,
    "location": null,
    "simulation": null
  }
}
```

#### Error Response

```json theme={null}
{
  "error": "Invalid query parameters",
  "message": "start_date must be in ISO 8601 format",
  "timestamp": "2023-12-21T10:30:56.789Z"
}
```

### Response Fields

| Field                 | Type    | Description                            |
| --------------------- | ------- | -------------------------------------- |
| `calls`               | array   | Array of emergency call objects        |
| `pagination`          | object  | Pagination information                 |
| `pagination.limit`    | integer | Maximum number of calls returned       |
| `pagination.offset`   | integer | Number of calls skipped                |
| `pagination.total`    | integer | Total number of calls matching filters |
| `pagination.has_more` | boolean | Whether more calls are available       |
| `filters`             | object  | Applied filters for reference          |

### Call Object Structure

| Field               | Type    | Description                           |
| ------------------- | ------- | ------------------------------------- |
| `conversation_id`   | string  | Unique conversation identifier        |
| `timestamp`         | integer | Unix timestamp of the call            |
| `agent_id`          | string  | ElevenLabs agent identifier           |
| `summary`           | string  | Summary of the emergency call         |
| `call_successful`   | boolean | Whether the call was successful       |
| `duration_secs`     | integer | Call duration in seconds              |
| `transcript_length` | integer | Number of transcript turns            |
| `created_at`        | string  | ISO 8601 timestamp of record creation |
| `emergency_type`    | string  | Type of emergency                     |
| `location`          | string  | Location description                  |
| `latitude`          | number  | Latitude coordinate                   |
| `longitude`         | number  | Longitude coordinate                  |
| `severity`          | string  | Emergency severity level              |
| `status`            | string  | Current call status                   |
| `simulation`        | boolean | Whether this is a simulated call      |
| `scenario`          | string  | Simulation scenario (if applicable)   |
| `scenario_name`     | string  | Human-readable scenario name          |

### HTTP Status Codes

| Code  | Description                                            |
| ----- | ------------------------------------------------------ |
| `200` | Success - Calls retrieved successfully                 |
| `400` | Bad Request - Invalid query parameters                 |
| `500` | Internal Server Error - Server error during processing |

### Filter Options

#### Emergency Types

| Value                   | Description                  |
| ----------------------- | ---------------------------- |
| `structure_fire`        | Structure fire emergency     |
| `evacuation_assistance` | Evacuation assistance needed |
| `trapped_person`        | Person trapped in emergency  |
| `medical_emergency`     | Medical emergency            |
| `shelter_information`   | Shelter information request  |
| `flooding`              | Flooding emergency           |
| `wind_damage`           | Wind damage emergency        |
| `power_outage`          | Power outage emergency       |
| `evacuation_needed`     | Evacuation needed            |
| `building_collapse`     | Building collapse            |
| `gas_leak`              | Gas leak emergency           |
| `debris_injury`         | Debris-related injury        |
| `building_damage`       | Building damage              |
| `vehicle_accident`      | Vehicle accident             |

#### Severity Levels

| Value      | Description                                     |
| ---------- | ----------------------------------------------- |
| `critical` | Critical emergency requiring immediate response |
| `high`     | High-priority emergency                         |
| `moderate` | Moderate-priority emergency                     |

#### Status Values

| Value        | Description                             |
| ------------ | --------------------------------------- |
| `active`     | Call is active and being processed      |
| `dispatched` | Emergency services have been dispatched |
| `enroute`    | Emergency services are en route         |
| `resolved`   | Emergency has been resolved             |
| `failed`     | Call processing failed                  |

### Pagination

The API supports pagination for large result sets:

#### Pagination Parameters

* **limit**: Maximum number of calls to return (1-1000)
* **offset**: Number of calls to skip from the beginning

#### Pagination Example

```bash theme={null}
# Get first 20 calls
curl -X GET "https://your-api-gateway-url/calls?limit=20&offset=0"

# Get next 20 calls
curl -X GET "https://your-api-gateway-url/calls?limit=20&offset=20"

# Get next 20 calls
curl -X GET "https://your-api-gateway-url/calls?limit=20&offset=40"
```

### Sorting

Calls are returned in descending order by timestamp (most recent first).

### Error Handling

#### Common Errors

| Error                 | Description                            | Solution                                         |
| --------------------- | -------------------------------------- | ------------------------------------------------ |
| `Invalid limit`       | Limit parameter out of range           | Use a value between 1 and 1000                   |
| `Invalid offset`      | Offset parameter is negative           | Use a non-negative integer                       |
| `Invalid date format` | Date parameters not in ISO 8601 format | Use ISO 8601 format (e.g., 2023-12-21T10:30:56Z) |
| `Database error`      | DynamoDB operation failed              | Check AWS credentials and permissions            |

#### Error Response Format

```json theme={null}
{
  "error": "Error type",
  "message": "Detailed error message",
  "timestamp": "2023-12-21T10:30:56.789Z",
  "error_code": "INVALID_PARAMETER"
}
```

### Rate Limits

* **Request rate**: 1000 requests per minute
* **Burst limit**: 500 requests per minute
* **Timeout**: 30 seconds per request

### Performance Considerations

#### Query Optimization

* **Use Filters**: Apply filters to reduce result set size
* **Limit Results**: Use appropriate limit values
* **Avoid Large Offsets**: Large offset values can be slow

#### Caching

The API implements caching for frequently accessed data:

* **Recent Calls**: Cached for 5 minutes
* **Filtered Results**: Cached for 2 minutes
* **Count Queries**: Cached for 10 minutes

### Best Practices

#### Efficient Queries

* **Use Specific Filters**: Apply specific filters to reduce result sets
* **Limit Results**: Use appropriate limit values for your use case
* **Monitor Performance**: Track query performance and optimize as needed

#### Error Handling

* **Implement Retry Logic**: Retry failed requests with exponential backoff
* **Handle Rate Limits**: Implement proper rate limiting in your client
* **Validate Parameters**: Validate query parameters before sending requests

#### Security

* **Use HTTPS**: Always use HTTPS for API requests
* **Validate Input**: Validate all query parameters
* **Handle Sensitive Data**: Be careful with sensitive information in logs

### SDK Examples

#### Python

```python theme={null}
import requests
from datetime import datetime, timedelta

class DispatchAICallsAPI:
    def __init__(self, base_url):
        self.base_url = base_url
    
    def get_calls(self, **filters):
        params = {}
        
        # Add filters to params
        for key, value in filters.items():
            if value is not None:
                params[key] = value
        
        response = requests.get(f"{self.base_url}/calls", params=params)
        
        if response.status_code == 200:
            return response.json()
        else:
            raise Exception(f"API Error: {response.status_code} - {response.text}")
    
    def get_recent_calls(self, limit=50):
        return self.get_calls(limit=limit)
    
    def get_calls_by_type(self, emergency_type, limit=50):
        return self.get_calls(emergency_type=emergency_type, limit=limit)
    
    def get_calls_by_severity(self, severity, limit=50):
        return self.get_calls(severity=severity, limit=limit)
    
    def get_calls_by_date_range(self, start_date, end_date, limit=50):
        return self.get_calls(
            start_date=start_date.isoformat(),
            end_date=end_date.isoformat(),
            limit=limit
        )

# Usage
api = DispatchAICallsAPI("https://your-api-gateway-url")

# Get recent calls
recent_calls = api.get_recent_calls(limit=20)
print(f"Found {recent_calls['pagination']['total']} calls")

# Get critical emergencies
critical_calls = api.get_calls_by_severity("critical", limit=10)
print(f"Found {len(critical_calls['calls'])} critical calls")

# Get calls from last week
week_ago = datetime.now() - timedelta(days=7)
week_calls = api.get_calls_by_date_range(week_ago, datetime.now())
print(f"Found {len(week_calls['calls'])} calls from last week")
```

#### JavaScript

```javascript theme={null}
class DispatchAICallsAPI {
  constructor(baseUrl) {
    this.baseUrl = baseUrl;
  }
  
  async getCalls(filters = {}) {
    const params = new URLSearchParams();
    
    // Add filters to params
    Object.entries(filters).forEach(([key, value]) => {
      if (value !== null && value !== undefined) {
        params.append(key, value);
      }
    });
    
    try {
      const response = await fetch(`${this.baseUrl}/calls?${params}`);
      
      if (!response.ok) {
        throw new Error(`HTTP error! status: ${response.status}`);
      }
      
      return await response.json();
    } catch (error) {
      console.error('Error fetching calls:', error);
      throw error;
    }
  }
  
  async getRecentCalls(limit = 50) {
    return this.getCalls({ limit });
  }
  
  async getCallsByType(emergencyType, limit = 50) {
    return this.getCalls({ emergency_type: emergencyType, limit });
  }
  
  async getCallsBySeverity(severity, limit = 50) {
    return this.getCalls({ severity, limit });
  }
  
  async getCallsByDateRange(startDate, endDate, limit = 50) {
    return this.getCalls({
      start_date: startDate.toISOString(),
      end_date: endDate.toISOString(),
      limit
    });
  }
}

// Usage
const api = new DispatchAICallsAPI('https://your-api-gateway-url');

// Get recent calls
api.getRecentCalls(20)
  .then(result => console.log(`Found ${result.pagination.total} calls`))
  .catch(error => console.error('Error:', error));

// Get critical emergencies
api.getCallsBySeverity('critical', 10)
  .then(result => console.log(`Found ${result.calls.length} critical calls`))
  .catch(error => console.error('Error:', error));

// Get calls from last week
const weekAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
const now = new Date();
api.getCallsByDateRange(weekAgo, now)
  .then(result => console.log(`Found ${result.calls.length} calls from last week`))
  .catch(error => console.error('Error:', error));
```

### Testing

#### Unit Testing

```python theme={null}
import unittest
from unittest.mock import patch, Mock

class TestCallsAPI(unittest.TestCase):
    def setUp(self):
        self.api = DispatchAICallsAPI("https://test-api.com")
    
    def test_get_recent_calls(self):
        with patch('requests.get') as mock_get:
            mock_response = Mock()
            mock_response.status_code = 200
            mock_response.json.return_value = {
                "calls": [],
                "pagination": {"total": 0}
            }
            mock_get.return_value = mock_response
            
            result = self.api.get_recent_calls(limit=20)
            self.assertEqual(result["pagination"]["total"], 0)
    
    def test_get_calls_by_type(self):
        with patch('requests.get') as mock_get:
            mock_response = Mock()
            mock_response.status_code = 200
            mock_response.json.return_value = {
                "calls": [{"emergency_type": "structure_fire"}],
                "pagination": {"total": 1}
            }
            mock_get.return_value = mock_response
            
            result = self.api.get_calls_by_type("structure_fire")
            self.assertEqual(len(result["calls"]), 1)
            self.assertEqual(result["calls"][0]["emergency_type"], "structure_fire")
```

#### Integration Testing

```bash theme={null}
# Test basic functionality
curl -X GET "https://your-api-gateway-url/calls?limit=10"

# Test filtering
curl -X GET "https://your-api-gateway-url/calls?emergency_type=structure_fire&limit=5"

# Test error handling
curl -X GET "https://your-api-gateway-url/calls?limit=2000"
```

<Note>
  **Data Privacy**: Ensure compliance with data privacy regulations when handling emergency call data. Consider data retention policies and access controls.
</Note>