Beam runs a local REST API while it’s up — no internet, no auth, just your own machine talking to its own Beam daemon at http://127.0.0.1:9091.

Send a Package

POST/api/package

Sends a Package synchronously over whichever channels you specify.

Headers

Name	Value
Content-Type	application/json

Body — exactly one of data, message, location, or waypoint:

Field	Type	Description
id	Int32 (optional)	Package ID
channels	Array of Satellite, Radio (Node only), Cellular (optional)	Channels to send over. Omit to use every available channel.
collapseKey	Int32 (optional)	Replaces any queued Package with a matching collapseKey — use it to swap in fresh data for one still in flight.
priority	Int32 (optional)	Higher priority Packages jump the queue. Default 11; Messages default to 12, Locations to 10, SOS to 100.
data	Data (one-of)	A raw base64 byte payload
message	Message (one-of)	A text message
location	Location (one-of)	A position report
waypoint	Waypoint (one-of)	A point of interest

Data

Raw bytes, base64-encoded.

Field	Type	Description
payload	String (base64)	Raw bytes to send

curl

curl http://127.0.0.1:9091/api/package \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "payload": "VGVzdAo="
    }
  }'

Body

{
  "data": {
    "payload": "VGVzdAo="
  }
}

Message

A text message.

Field	Type	Description
content	String	Message content

curl

curl http://127.0.0.1:9091/api/package \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "content": "Hello from space!"
    }
  }'

Body

{
  "message": {
    "content": "Hello from space!"
  }
}

Location

A position report.

Field	Type	Description
latitude	Double	Latitude (WGS84)
longitude	Double	Longitude (WGS84)
timestamp	String (ISO 8601, optional)	When the position was recorded
altitude	Float (optional)	Altitude above mean sea level
speedOverGround	Float (optional)	Speed over ground, in m/s
courseOverGround	Float (optional)	Degrees clockwise from true north

curl

curl http://127.0.0.1:9091/api/package \
  -H "Content-Type: application/json" \
  -d '{
    "location": {
      "latitude": "37.781001",
      "longitude": "-122.393456",
      "timestamp": "2023-04-12T19:15:14Z"
    }
  }'

Body

{
  "location": {
    "latitude": "37.781001",
    "longitude": "-122.393456",
    "timestamp": "2023-04-12T19:15:14Z"
  }
}

Waypoint

A point of interest.

Field	Type	Description
latitude	Double	Latitude (WGS84)
longitude	Double	Longitude (WGS84)
timestamp	String (ISO 8601, optional)	Timestamp
name	String	Name of the point of interest
notes	String (optional)	Additional notes

curl

curl http://127.0.0.1:9091/api/package \
  -H "Content-Type: application/json" \
  -d '{
    "waypoint": {
      "latitude": "37.819466",
      "longitude": "-122.478628",
      "timestamp": "2023-04-12T19:15:14Z",
      "name": "Golden Gate Bridge"
    }
  }'

Body

{
  "waypoint": {
    "latitude": "37.819466",
    "longitude": "-122.478628",
    "timestamp": "2023-04-12T19:15:14Z",
    "name": "Golden Gate Bridge"
  }
}

Response

The response carries a status. These are terminal statuses only.

200

{
  "id": 1,
  "status": "Delivered",
  "data": {
    "payload": ""
  }
}

400

{
  "error": "Invalid request"
}

429

{
  "error": "Too many requests"
}

Package status

Status	Description
Delivered	Sent successfully over the channel. This isn’t end-to-end confirmation — over satellite, for example, it means the Package reached the satellite gateway, not that the target client has it yet.
Error	Failed to send over every channel.
Collapsed	Replaced by a more recent Package sharing the same collapseKey.
Canceled	Canceled by a call to /api/package/{id}/cancel.