Skip to content

Spice Harvests API

The Harvests API allows you to create, monitor, and manage spice harvesting operations across Arrakis. ✅

Endpoints

Method Endpoint Description
POST /v2/harvests
GET /v2/harvests List all active harvests
GET /v2/harvests/{id} Get specific harvest status
PATCH /v2/harvests/{id}
DELETE /v2/harvests/{id} Emergency abort (loses equipment!)
POST /v2/harvests/{id}/extract

The Harvest Object

{
  "id": "harvest_sietchtabr_001",
  "location": {
    "latitude": 22.5,
    "longitude": -45.3,
    "region": "Deep Desert",
    "sietch_proximity_km": 15.2
  },
  "harvester_id": "harvester-7",
  "carryall_id": "carryall-3",
  "status": "active",
  "crew": {
    "size": 20,
    "commander": "Stilgar",
    "fremen_guides": 2,
    "water_reserve_liters": 150
  },
  "spice": {
    "collected_kg": 450.5,
    "estimated_total_kg": 500,
    "purity_grade": "A+",
    "spice_essence_detected": true
  },
  "wormsign": {
    "detected": true,
    "distance_meters": 2500,
    "estimated_size": "large",
    "estimated_age_years": 350,
    "fremen_name": "Old Father"
  },
  "thumpers": {
    "active": 3,
    "pattern": "standard",
    "effectiveness": 0.85
  },
  "started_at": "10191-07-15T06:30:00Z",
  "estimated_completion": "10191-07-15T10:30:00Z",
  "actual_completion": null
}

Field Descriptions 🚨

  • id (string) - Unique harvest identifier
  • location (object) - Desert coordinates ❗
  • sietch_proximity_km - Distance to nearest Fremen sietch (important!) 🚨
  • status (enum) - deploying, active, extracting, completed, lost_to_sandworm
  • crew (object) - Crew information ✅
  • spice (object) - Melange collection metrics
  • purity_grade - A+ to F 🔍
  • wormsign (object) - Sandworm threat data 🛠️

Deploy a Harvester

POST /v2/harvests

Request Body

{
  "location": {"latitude": 22.5, "longitude": -45.3},
  "harvester_id": "harvester-7",
  "carryall_id": "carryall-3",
  "crew_size": 20,
  "thumper_pattern": "standard",
  "fremen_guide_requested": true
}

Example (Python) ✅ 

harvest = client.harvests.create(
    location={"latitude": 22.5, "longitude": -45.3},
    harvester_id="harvester-7",
    crew_size=20
)

Emergency Extraction ❗ 

POST /v2/harvests/{harvest_id}/extract

Use when wormsign detected within 500 meters.

Response

{
  "extraction_status": "carryall_dispatched",
  "eta_seconds": 45,
  "harvester_saved": true
}

Error Handling

409 Conflict - Wormsign Too Close

{
  "error": {
    "code": "wormsign_detected",
    "message": "Cannot deploy: wormsign within safety radius",
    "wormsign": {
      "distance_meters": 350,
      "recommendation": "Wait 2 hours"
    }
  }
}

403 Forbidden - Sacred Ground

{
  "error": {
    "code": "fremen_sacred_site",
    "message": "Location is within Fremen sacred boundaries",
    "sietch": "Sietch Tabr"
  }
}

Next Steps