API Reference

Complete API documentation for the Enterprise Balloon Platform

Navigation
Simulation Logistics Campaign Inventory Calculator Reports Database

Simulation Endpoints

POST /api/simulate

Run a new balloon simulation

Request Body:
{ "balloon_type": "KCI-1200", "payload_mass": 2.5, "launch_lat": 40.7128, "launch_lon": -74.0060, "launch_datetime": "2024-03-15T12:00:00Z", "target_altitude": 30000, "simulation_type": "forward" }
Response:
{ "simulation_id": "uuid-string", "status": "queued", "estimated_duration": 180, "queue_position": 1 }
GET /api/results/{simulation_id}

Get simulation results

Response:
{ "status": "completed", "trajectory": [...], "max_altitude": 30542, "flight_duration": 175.3, "landing_location": { "lat": 41.234, "lon": -72.891 } }
GET /api/simulations

List user's simulations

Parameter Type Description
page integer Page number (default: 1)
limit integer Results per page (default: 20)
status string Filter by status

Logistics Endpoints

GET /logistics/api/balloons

Get all balloon types with specifications and costs

Response:
[ { "id": 1, "manufacturer": "Kaymont", "model": "KCI-1200", "mass_grams": 1200, "burst_altitude_m": 30000, "unit_cost_usd": 130.00, "vendor_name": "Kaymont/Pawan" } ]
POST /logistics/api/balloons

Add new balloon type

Request Body:
{ "manufacturer": "Totex", "model": "TA-1500", "mass_grams": 1500, "burst_altitude_m": 32000, "unit_cost_usd": 150.00, "vendor_id": 1 }
PUT /logistics/api/balloons/{id}

Update balloon type information

GET /logistics/api/gases

Get all gas types and suppliers

Response:
[ { "id": 1, "gas_type": "Helium", "purity_percent": 99.9, "container_type": "K-Cylinder", "volume_m3": 7.8, "cost_per_m3_usd": 42.00, "vendor_name": "Airgas" } ]
GET /logistics/api/payloads

Get all payload models

GET /logistics/api/vendors

Get all vendors

GET /logistics/api/exchange-rates

Get current exchange rates

POST /logistics/api/exchange-rates/update

Update exchange rates from external API

Campaign Endpoints

GET /campaign/api/campaigns

List all campaigns

Response:
[ { "id": 1, "name": "Summer Research 2024", "type": "research", "status": "active", "start_date": "2024-06-01", "end_date": "2024-08-31", "mission_count": 12, "total_cost": 45000.00 } ]
POST /campaign/api/campaigns

Create new campaign

Request Body:
{ "name": "Arctic Study 2024", "type": "research", "start_date": "2024-07-01", "end_date": "2024-07-31", "description": "High-latitude atmospheric research", "missions": [ { "name": "Mission Alpha", "launch_lat": 71.2906, "launch_lon": -156.7886, "launch_datetime": "2024-07-05T10:00:00Z", "balloon_id": 1, "payload_ids": [1, 2] } ] }
GET /campaign/api/campaigns/{id}

Get campaign details including all missions

PUT /campaign/api/campaigns/{id}

Update campaign information

POST /campaign/api/campaigns/{id}/missions

Add mission to campaign

POST /campaign/api/missions/{id}/simulate

Run simulation for a mission

GET /campaign/api/campaigns/{id}/cost-analysis

Get detailed cost breakdown for campaign

Inventory Endpoints

GET /logistics/api/inventory

Get inventory items by category

Response:
{ "balloons": [ { "id": 1, "name": "Kaymont KCI-1200", "quantity": 25, "location": "Main Warehouse", "condition": "new" } ], "gases": [...], "payloads": [...], "consumables": [...] }
POST /logistics/api/inventory

Add new inventory item

Request Body:
{ "item_type": "balloon", "balloon_type_id": 1, "quantity": 10, "serial_number": "KCI-2024-001", "location": "Main Warehouse", "condition": "new" }
PUT /logistics/api/inventory/{id}

Update inventory item quantity or status

POST /logistics/api/inventory/{id}/reserve

Reserve inventory for campaign

Request Body:
{ "campaign_id": 1, "from_date": "2024-07-01", "until_date": "2024-07-31" }

Quick Calculator Endpoints

POST /logistics/api/quick-calc/helium

Calculate helium requirements

Request Body:
{ "balloon_mass_g": 1200, "payload_mass_kg": 2.5, "target_ascent_rate": 5.0 }
Response:
{ "volume_m3": 4.2, "lift_kg": 3.8, "cost_usd": 176.40 }
POST /logistics/api/quick-calc/recovery

Calculate recovery distance and costs

POST /logistics/api/quick-calc/mission-cost

Calculate total mission cost

Reports Endpoints

GET /logistics/api/reports/cost-breakdown

Get cost breakdown report

Parameter Type Description
start_date date Start of reporting period
end_date date End of reporting period
GET /logistics/api/reports/resource-utilization

Get resource utilization report

GET /logistics/api/reports/inventory-value

Get current inventory value report

Database Management

GET /logistics/api/export/{category}

Export data as CSV

Categories: balloons, gases, payloads, inventory

POST /logistics/api/import/{category}

Import data from CSV file

Categories: balloons, gases, payloads

Authentication

Session-Based Authentication

All API endpoints require authentication via session cookies. Login through the web interface to establish a session.

CORS Configuration

Cross-origin requests are restricted. Configure CORS settings in production for external API access.

Response Codes

Code Status Description
200 OK Request successful
201 Created Resource created successfully
400 Bad Request Invalid request parameters
401 Unauthorized Authentication required
404 Not Found Resource not found
500 Internal Server Error Server error occurred

Rate Limiting

  • Simulation endpoints: 10 requests per minute
  • Data modification endpoints: 30 requests per minute
  • Read-only endpoints: 100 requests per minute
  • Export endpoints: 5 requests per minute