REST API

Swarm AI provides a REST API for programmatic device control, useful for building custom integrations, dashboards, and automated workflows.

Base URL

https://swarm.cheshirelabs.io

Authentication

All requests require an API key in the X-API-Key header:

curl -H "X-API-Key: your-api-key" \
  https://swarm.cheshirelabs.io/api/devices

Interactive Documentation

The complete API reference with request/response schemas is available at:

swarm.cheshirelabs.io/docs

The interactive docs let you:

• Browse all endpoints
• See request/response schemas
• Try API calls in your browser

Quick Reference

Device Endpoints

Method	Endpoint	Description
GET	/api/devices	List connected devices
GET	/api/devices/{device_id}	Get device info
GET	/api/devices/{device_id}/capabilities	Get device capabilities
GET	/api/devices/{device_id}/initialized	Check if initialized
POST	/api/devices/{device_id}/initialize	Initialize device
POST	/api/devices/{device_id}/shake	Shake device
POST	/api/devices/{device_id}/centrifuge	Run centrifuge
POST	/api/devices/{device_id}/seal	Seal plate
POST	/api/devices/{device_id}/stop	Emergency stop
POST	/api/devices/{device_id}/open	Open door/lid
POST	/api/devices/{device_id}/close	Close door/lid
POST	/api/devices/{device_id}/lock_plate	Lock plate
POST	/api/devices/{device_id}/unlock_plate	Unlock plate
POST	/api/devices/{device_id}/set_temperature	Set temperature
GET	/api/devices/{device_id}/get_temperature	Get temperature

Teachpoint Endpoints

Method	Endpoint	Description
GET	/api/teachpoints?device_id=...	List teachpoints for device
GET	/api/teachpoints/{device_id}/{name}	Get specific teachpoint
POST	/api/teachpoints	Create teachpoint
PUT	/api/teachpoints/{device_id}/{name}	Update teachpoint
DELETE	/api/teachpoints/{device_id}/{name}	Delete teachpoint
POST	/api/teachpoints/bulk	Bulk import teachpoints
GET	/api/teachpoints/export/{device_id}	Export all teachpoints

Example Requests

List Devices

curl -H "X-API-Key: your-api-key" \
  https://swarm.cheshirelabs.io/api/devices

Response:

{
  "devices": [
    {
      "device_id": "lab1-shaker-01",
      "type": "shaker",
      "name": "Plate Shaker",
      "is_initialized": true
    }
  ]
}

Shake Device

curl -X POST \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"speed": 500, "duration": 30}' \
  https://swarm.cheshirelabs.io/api/devices/lab1-shaker-01/shake

Response:

{
  "success": true,
  "message": "Shake completed"
}

Create Teachpoint

curl -X POST \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": "robot-arm",
    "name": "source_rack",
    "coord_type": "cartesian",
    "coords": {
      "x": 100.5,
      "y": 200.0,
      "z": 50.0,
      "yaw": 0,
      "pitch": 90,
      "roll": 0
    }
  }' \
  https://swarm.cheshirelabs.io/api/teachpoints

Error Responses

Errors return appropriate HTTP status codes:

Status	Meaning
400	Bad request (invalid parameters)
401	Unauthorized (invalid or missing API key)
404	Not found (device or teachpoint doesn't exist)
500	Server error

Error response body:

{
  "detail": "Device lab1-shaker-01 not found"
}

Rate Limits

During the beta, there are no strict rate limits. For production use, please contact us to discuss your needs.

What's Next?

• MCP Tools Reference - MCP tool documentation
• Troubleshooting - Common issues