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

# Simulation API

> Generate emergency scenarios and test system performance

## Simulation Endpoint

Generate realistic emergency scenarios for testing and training purposes with access911.

### Endpoint

```
POST https://v2y08vmfga.execute-api.us-east-1.amazonaws.com/simulate
```

### Request

#### Headers

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

#### Body Parameters

| Parameter    | Type    | Required | Default                     | Description                                    |
| ------------ | ------- | -------- | --------------------------- | ---------------------------------------------- |
| `scenario`   | string  | No       | `la_wildfire`               | Emergency scenario to simulate                 |
| `num_calls`  | integer | No       | `1`                         | Number of emergency calls to generate (1-1000) |
| `table_name` | string  | No       | `wildfire-simulation-calls` | DynamoDB table name                            |

#### Available Scenarios

| Scenario ID         | Name                     | Description                     |
| ------------------- | ------------------------ | ------------------------------- |
| `la_wildfire`       | Los Angeles Wildfire     | Wildfire emergency simulation   |
| `nashville_tornado` | Nashville Tornado        | Tornado outbreak simulation     |
| `earthquake_sf`     | San Francisco Earthquake | Earthquake emergency simulation |
| `hurricane_florida` | Florida Hurricane        | Hurricane emergency simulation  |

### Request Examples

#### Basic Simulation

```bash theme={null}
curl -X POST https://v2y08vmfga.execute-api.us-east-1.amazonaws.com/simulate \
  -H "Content-Type: application/json" \
  -d '{
    "scenario": "nashville_tornado",
    "num_calls": 25
  }'
```

#### High-Volume Simulation

```bash theme={null}
curl -X POST https://v2y08vmfga.execute-api.us-east-1.amazonaws.com/simulate \
  -H "Content-Type: application/json" \
  -d '{
    "scenario": "la_wildfire",
    "num_calls": 100,
    "table_name": "emergency-calls"
  }'
```

#### Custom Table Simulation

```bash theme={null}
curl -X POST https://v2y08vmfga.execute-api.us-east-1.amazonaws.com/simulate \
  -H "Content-Type: application/json" \
  -d '{
    "scenario": "earthquake_sf",
    "num_calls": 50,
    "table_name": "test-emergency-calls"
  }'
```

### Response

#### Success Response

```json theme={null}
{
  "message": "Generated 25 calls for Nashville Tornado Outbreak",
  "scenario": "nashville_tornado",
  "total_requested": 25,
  "successful": 25,
  "failed": 0,
  "generation_method": "Templates (fast mode)",
  "sample_calls": [
    {
      "call_id": "NASHVILLE_TORNADO-1703123456-1234",
      "location": "Downtown Nashville",
      "emergency_type": "building_damage"
    },
    {
      "call_id": "NASHVILLE_TORNADO-1703123457-1235",
      "location": "East Nashville",
      "emergency_type": "trapped_person"
    }
  ],
  "errors": []
}
```

#### Error Response

```json theme={null}
{
  "error": "Unknown scenario: invalid_scenario",
  "available_scenarios": [
    "la_wildfire",
    "nashville_tornado",
    "earthquake_sf",
    "hurricane_florida"
  ]
}
```

### Response Fields

| Field               | Type    | Description                                                          |
| ------------------- | ------- | -------------------------------------------------------------------- |
| `message`           | string  | Success message describing the operation                             |
| `scenario`          | string  | The scenario that was simulated                                      |
| `total_requested`   | integer | Number of calls requested                                            |
| `successful`        | integer | Number of calls successfully generated                               |
| `failed`            | integer | Number of calls that failed to generate                              |
| `generation_method` | string  | Method used for generation ("Bedrock AI" or "Templates (fast mode)") |
| `sample_calls`      | array   | Sample of generated calls (first 5)                                  |
| `errors`            | array   | List of any errors encountered                                       |

### HTTP Status Codes

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

### Rate Limits

* **Maximum calls per request**: 1000
* **Rate limit**: 100 requests per minute
* **Burst limit**: 500 requests per minute

### Generation Methods

#### AI-Powered Generation (≤20 calls)

For small batches, the API uses AWS Bedrock AI to generate human-like call summaries:

```json theme={null}
{
  "generation_method": "Bedrock AI",
  "quality": "High",
  "processing_time": "2-5 seconds"
}
```

#### Template-Based Generation (>20 calls)

For large batches, the API uses templates for high throughput:

```json theme={null}
{
  "generation_method": "Templates (fast mode)",
  "quality": "Good",
  "processing_time": "1-3 seconds"
}
```

### Call Data Structure

Each generated call includes:

```json theme={null}
{
  "call_id": "NASHVILLE_TORNADO-1703123456-1234",
  "timestamp": 1703123456,
  "created_at": "2023-12-21T10:30:56.789Z",
  "location": {
    "latitude": "36.1627",
    "longitude": "-86.7816",
    "address": "1234 Broadway, Downtown Nashville",
    "area": "Downtown Nashville"
  },
  "emergency_type": "building_damage",
  "severity": "critical",
  "description": "severe structural damage from tornado",
  "summary": "Caller reported severe structural damage from tornado at 1234 Broadway, Downtown Nashville. Fire and EMS units dispatched to scene.",
  "duration_secs": 180,
  "caller_phone": "+16155551234",
  "status": "active",
  "simulation": true,
  "scenario": "nashville_tornado",
  "scenario_name": "Nashville Tornado Outbreak"
}
```

### Error Handling

#### Common Errors

| Error               | Description                  | Solution                                  |
| ------------------- | ---------------------------- | ----------------------------------------- |
| `Unknown scenario`  | Invalid scenario ID provided | Use one of the available scenarios        |
| `Invalid num_calls` | Number of calls out of range | Use a number between 1 and 1000           |
| `DynamoDB error`    | Database operation failed    | Check table permissions and configuration |
| `Bedrock error`     | AI generation failed         | Falls back to template generation         |

#### Error Response Format

```json theme={null}
{
  "error": "Error description",
  "details": "Additional error information",
  "timestamp": "2023-12-21T10:30:56.789Z"
}
```

### Best Practices

#### Performance Optimization

* **Start Small**: Begin with 10-20 calls to test system responsiveness
* **Monitor Performance**: Watch response times and error rates
* **Use Appropriate Scenarios**: Choose scenarios that match your testing needs

#### Error Handling

* **Implement Retry Logic**: Retry failed requests with exponential backoff
* **Handle Rate Limits**: Implement proper rate limiting in your client
* **Monitor Errors**: Track error rates and types for debugging

#### Security

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

### SDK Examples

#### Python

```python theme={null}
import requests
import json

def generate_emergency_calls(scenario, num_calls):
    url = "https://v2y08vmfga.execute-api.us-east-1.amazonaws.com/simulate"
    payload = {
        "scenario": scenario,
        "num_calls": num_calls
    }
    
    response = requests.post(url, json=payload)
    
    if response.status_code == 200:
        return response.json()
    else:
        raise Exception(f"API Error: {response.status_code} - {response.text}")

# Usage
result = generate_emergency_calls("nashville_tornado", 25)
print(f"Generated {result['successful']} calls")
```

#### JavaScript

```javascript theme={null}
async function generateEmergencyCalls(scenario, numCalls) {
  const url = 'https://v2y08vmfga.execute-api.us-east-1.amazonaws.com/simulate';
  const payload = {
    scenario: scenario,
    num_calls: numCalls
  };
  
  try {
    const response = await fetch(url, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(payload)
    });
    
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    
    const result = await response.json();
    return result;
  } catch (error) {
    console.error('Error generating calls:', error);
    throw error;
  }
}

// Usage
generateEmergencyCalls('nashville_tornado', 25)
  .then(result => console.log(`Generated ${result.successful} calls`))
  .catch(error => console.error('Error:', error));
```

### Testing

#### Unit Testing

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

class TestSimulationAPI(unittest.TestCase):
    def test_successful_simulation(self):
        with patch('requests.post') as mock_post:
            mock_response = Mock()
            mock_response.status_code = 200
            mock_response.json.return_value = {
                "successful": 25,
                "failed": 0
            }
            mock_post.return_value = mock_response
            
            result = generate_emergency_calls("nashville_tornado", 25)
            self.assertEqual(result["successful"], 25)
            self.assertEqual(result["failed"], 0)
```

#### Integration Testing

```bash theme={null}
# Test basic functionality
curl -X POST https://v2y08vmfga.execute-api.us-east-1.amazonaws.com/simulate \
  -H "Content-Type: application/json" \
  -d '{"scenario": "nashville_tornado", "num_calls": 5}'

# Test error handling
curl -X POST https://v2y08vmfga.execute-api.us-east-1.amazonaws.com/simulate \
  -H "Content-Type: application/json" \
  -d '{"scenario": "invalid_scenario", "num_calls": 5}'
```

<Note>
  **Testing Environment**: Use the simulation API for testing and training purposes only. For production emergency response, ensure proper integration with your existing 911 systems.
</Note>