Skip to main content

​
Agent Protocol Specification

Version: 0.1.0 The RotaStellar Agent Protocol defines how satellite-side agents communicate with the Console API. It is a pull-based protocol designed for intermittent satellite connectivity.

​
Authentication

All agent requests authenticate via API key in the X-API-Key header. The agent identifies itself via the X-Agent-ID header. 
X-API-Key: rs_live_...
X-Agent-ID: sat-25544
API keys are created in Mission Control under Developer > API Keys. Keys are hashed (SHA-256) server-side and compared against stored hashes. Keys can be revoked at any time from the Console.

​
Agent Lifecycle

​
1. Register

The agent registers with the Console on first startup. This creates or updates an agent record. 
POST /api/agent/register
Request: 
{
  "agent_id": "sat-25544",
  "satellite_id": "25544",
  "satellite_name": "ISS (ZARYA)",
  "agent_version": "0.1.0"
}
Response (201): 
{
  "id": "sat-25544",
  "status": "idle"
}
If the agent_id already exists for this user, the record is updated (upsert).

​
2. Poll for Workloads

The agent polls periodically for pending deployments assigned to its satellite. 
GET /api/agent/workloads
Response (200) — Work available: 
{
  "plan_id": "abc-123",
  "deployment_id": "dep-456",
  "satellite_id": "25544",
  "plan_data": { ... },
  "events": [
    {
      "type": "job.accepted",
      "timestamp": "2026-03-07T12:00:00Z",
      "job_id": "preset-001",
      "payload": { "preset": "split-learning", "steps": 8 }
    }
  ]
}
Response (204) — No work available. The agent should sleep for poll_interval_s and retry. The server returns the oldest pending deployment where:
  • mode = 'live'
  • satellite_id matches the agent’s registered satellite
  • status = 'pending'
On dispatch, the server updates the deployment status to dispatched.

​
3. Report Events

During execution, the agent reports events as they occur. 
POST /api/deployments/{deployment_id}/events
Request: 
{
  "type": "step.completed",
  "timestamp": "2026-03-07T14:23:45Z",
  "job_id": "preset-001",
  "step_id": "feature_extraction",
  "payload": {
    "duration_s": 180,
    "location": "onboard",
    "data_output_mb": 10.5
  }
}
Response (201): 
{
  "id": "evt-789"
}
The server stores the event and updates the deployment status based on event type:
  • job.accepted (when dispatched) → deployment status = running
  • job.completed → deployment status = completed
  • job.failed → deployment status = failed

​
4. Report Telemetry

Agents send periodic heartbeats with health data. 
POST /api/agent/telemetry
Request: 
{
  "agent_id": "sat-25544",
  "status": "executing",
  "timestamp": "2026-03-07T14:23:45Z",
  "cpu_percent": 67.5,
  "memory_mb": 128.0,
  "battery_percent": 82.0,
  "temperature_c": 34.2
}
Response (200): 
{
  "ok": true
}
All fields except agent_id, status, and timestamp are optional.

​
Event Types

All events follow this structure: 
{
  "type": "<event_type>",
  "timestamp": "<ISO 8601>",
  "job_id": "<string>",
  "step_id": "<string | null>",
  "payload": { ... }
}

​
Lifecycle Events

TypeDescriptionPayload
job.acceptedWorkload received and queuedpreset, category, steps, security
plan.createdExecution plan finalizedsegments, windows_used, total_duration_s
job.completedAll steps finished successfullytotal_duration_s, status, delivery_confidence
job.failedExecution failedtotal_duration_s, status

​
Placement Events

TypeDescriptionPayload
placement.decidedStep placement decisionlocation (onboard/ground), reason

​
Compute Events

TypeDescriptionPayload
step.startedCompute step beginslocation, window, window_label
step.progressProgress updatepercent (25, 50, 75)
step.completedCompute step finishedduration_s, location, data_output_mb

​
Transfer Events

TypeDescriptionPayload
transfer.startedData transfer initiatedtype, raw_data_mb, total_transfer_mb, fec_scheme
transfer.pass_startedGround station pass beginsground_station, station_name, elevation_peak_deg
transfer.progressTransfer progressdata_transferred_mb, total_mb
transfer.pass_completedPass finisheddata_transferred_mb, ground_station
transfer.completedAll transfers donetotal_transferred_mb, duration_s
transfer.retransmissionBlocks retransmitted (BER)blocks_retransmitted, ber

​
Security Events

TypeDescriptionPayload
security.encryptedData encryptedalgorithm, data_mb
security.key_exchangeKey exchange performedduration_s, encryption

​
Checkpoint Events

TypeDescriptionPayload
checkpoint.savedState persistedcheckpoint_number, progress_fraction
checkpoint.predictedHazard prediction generatedhazards_count, checkpoints_count, next_hazard, max_safe_window_s, overhead_fraction

​
Orbital Compute Primitive Events

Eclipse, window, and pass steps emit specialized events. See Orbital Compute Primitives for details.
TypeDescriptionPayload
eclipse_step.startedEclipse step beginsenergy_budget_j, eclipse_policy, actual_battery_wh
eclipse_step.completedEclipse step finishedenergy_consumed_j, actual_battery_wh, actual_temperature_c
window_step.startedWindow step beginsplanned_tier, quality_tiers, actual_battery_percent
window_step.degradedTier downgradedfrom_tier, to_tier, reason
window_step.completedWindow step finishedachieved_tier, output_quality, degradations
pass_step.startedPass step beginssequence_index, sequence_total, actual_battery_percent
pass_step.completedPass step finishedsequence_index, sequence_total, merge_strategy

​
Constellation Events

Multi-satellite DAG orchestration events. See Constellation Execution for details.
TypeDescriptionPayload
constellation.step_assignedStep assigned to satellitestep_id, step_name, satellite_id, window_id
constellation.step_startedAgent began executing stepstep_id, actual_battery_percent
constellation.step_completedStep finishedstep_id, duration_s, actual_battery_percent
constellation.failoverStep failed, reassigningstep_id, from_satellite, to_satellite, reason
constellation.satellite_completeAll assigned steps donesatellite_id, completed_count

​
ISL Transfer Events

TypeDescriptionPayload
isl_transfer.startedISL transfer initiatedsrc_satellite, dst_satellite, data_mb, hops, route
isl_transfer.hop_completedOne ISL hop donefrom, to, data_mb, quality, latency_ms, bw_mbps
isl_transfer.completedFull transfer donetotal_time_s, total_data_mb, hops, reliability

​
Error Handling

All error responses follow this format: 
{
  "error": "Human-readable error message"
}
StatusMeaning
400Invalid request body
401Missing or invalid API key
403API key valid but insufficient permissions
404Resource not found
409Conflict (e.g., deployment already dispatched)
429Rate limited
500Server error

​
Rate Limits

EndpointLimit
PollMax 1 request per 10 seconds per agent
EventsMax 100 events per minute per deployment
TelemetryMax 1 request per 30 seconds per agent

​
Versioning

The protocol version is included in the User-Agent header: 
User-Agent: rotastellar-agent/0.1.0
Breaking changes will increment the minor version until 1.0. After 1.0, semantic versioning applies.