Fleet

Overview

These endpoints are for software running on a robot: report that it is online, upload measurements, and report update progress to the operator. Each enrolled robot acts as itself; the server finds its robot record from the credential, so you never choose another robot's ID. Use the separate operator fleet API to manage a whole fleet.

Identity selects the robot

GET /api/v1/robots/me and every write resolve the robot from the credential. A service agent not linked to a robot receives 404; a caller cannot redirect a heartbeat or telemetry batch with a request field.

Telemetry supports bounded backfill

One batch contains 1 through 500 readings. recorded_at may be seven days old or up to five minutes ahead, enabling offline drain with modest clock skew; valid readings can be accepted while invalid indices are reported in errors.

A batch ID is consumed once

Replaying an accepted batch_id returns duplicate: true and writes nothing even when the new body differs. A partially valid first batch also consumes the ID, so correct rejected readings under a new batch ID rather than retrying changed content.

Trusted position is not a telemetry backfill

POST /api/v1/robots/me/heartbeat accepts a numeric lat/lng location only when observed_at is at most five minutes old or 30 seconds ahead and newer than the previous trusted fix. It appends a sample and evaluates active geofences atomically. GET /api/v1/robots/me/locations needs fleet:read and pages recent fixes with a signed cursor (25 default, 100 max) while returning current trusted position and active boundary state separately. The seven-day telemetry batch backlog does not apply to heartbeat location.

OTA success is device evidence

For a signed artifact rollout, consume the fleet.ota.install or fleet.ota.rollback command and keep its command_id. The device must fetch and verify actual bytes against SHA-256 and Ed25519 metadata before installing or reporting completed. POST /api/v1/robots/me/ota-attempts/:id/acknowledge with matching command_id, monotonic status and verified_version on completed/rolled_back. The server validates metadata and correlation; it does not fetch or verify bytes on the device's behalf. A legacy single-target OTA row may be partial and is not a signed rollout.

How it works

1. Confirm the linked unit

   Read /api/v1/robots/me after enrollment and retain its robot ID only for logs and reconciliation; do not treat it as an input to self-service writes.

2. Publish liveness separately

   Send heartbeats with battery, location, firmware, or metadata. The server sets status online and updates last-seen time; any client-supplied status is ignored.

3. Rehydrate safety on reconnect

   Read /api/v1/robots/me/locations for current fix and geofence_states, then accept geofence.breach/clear events only with a strictly larger transition_version for the same fence and a non-older geometry_revision. Event IDs are stable for retries; realtime delivery may repeat or arrive out of order.

4. Drain measurements in stable batches

   Group readings into at most 500, assign a unique batch ID, and inspect both accepted and per-index errors. Accepted readings count against the monthly telemetry-points quota.

Examples

These examples are illustrative. Replace the sample values with your own. Keep credentials in environment variables or a secret manager, never in client-side code.

export AGENTOPS_BASE_URL="https://robotscenter.net"
export ROBOT_TOKEN="machine_token_with_fleet_write"
export TELEMETRY_BATCH_ID="robot-17-2026-09-16T12:00:00Z"

jq -n --arg batch_id "$TELEMETRY_BATCH_ID" \
  '{batch_id: $batch_id, readings: [{metric_name: "battery.voltage", metric_value: 48.6, unit: "V", status: "normal", recorded_at: "2026-09-16T11:59:55Z"}, {metric_name: "motor.temperature", metric_value: 61.2, unit: "C", status: "warning", recorded_at: "2026-09-16T11:59:58Z"}]}' |
  curl --fail-with-body --silent --show-error \
    -X POST -H 'content-type: application/json' \
    -H "Authorization: Bearer $ROBOT_TOKEN" \
    --data-binary @- "$AGENTOPS_BASE_URL/api/v1/robots/me/telemetry" | jq .

Troubleshooting

Self lookup returns 404

The authenticated service agent is not linked to a robot, or the linked robot no longer exists. Claim a robot enrollment rather than using a general service-agent credential.

Telemetry returns 200 with errors

The batch was partially valid. Keep accepted points as committed, correct only the rejected indices, and send those corrections under a fresh batch ID.

The same device sees 401 or 410

Normal decommissioning revokes the identity and usually produces 401. A surviving valid credential against a decommissioned robot is refused with 410 robot-decommissioned; neither response is retryable device work.

Telemetry returns 429

Distinguish the per-credential request limit from the workspace's telemetry_points_per_month quota in the problem body, then honor Retry-After or resolve the plan limit.

OTA command was accepted but no terminal result appears

Do not infer completion or blindly reinstall. Inspect the bound attempt command_id and local version, then send the matching attempt-scoped ACK. A transport interruption after acceptance is outcome unknown, not a server-certified failure.

Endpoint reference

Ready to integrate? Open an endpoint for its required permissions, request fields, response format, and status codes. The examples above explain the workflow; these details define each individual request.

{
  "battery_level": 82,
  "capabilities": [
    "navigate",
    "pickup",
    "delivery"
  ],
  "firmware_version": "3.2.1",
  "id": "d2c9a4df-c6ad-4016-9ba4-30c1c6d53a22",
  "inserted_at": "2026-03-25T08:00:00Z",
  "last_seen_at": "2026-03-27T09:12:10Z",
  "location": {
    "lat": 41.717,
    "lng": 44.793,
    "zone": "A3"
  },
  "manufacturer": "RoboWorks",
  "metadata": {
    "shift": "day"
  },
  "model": "AX-7",
  "name": "Aisle Runner 7",
  "robot_type": "amr",
  "serial_number": "AMR-AX7-0042",
  "service_agent_id": "f4d49601-3477-4c9d-b896-ac08a26a3147",
  "status": "online",
  "tags": [
    "night-shift",
    "warehouse-b"
  ],
  "updated_at": "2026-03-27T09:12:10Z",
  "workspace_id": "4ce4d170-e6d5-4118-8f4d-fac69dc099ea"
}

{
  "id": "b3ec0b4e-64be-44f3-a5f6-e6f54c8bf190",
  "inserted_at": "2026-03-27T09:11:30Z",
  "metadata": {},
  "metric_name": "battery_health",
  "metric_value": 76.5,
  "recorded_at": "2026-03-27T09:11:30Z",
  "robot_id": "d2c9a4df-c6ad-4016-9ba4-30c1c6d53a22",
  "status": "warning",
  "unit": "percent",
  "updated_at": "2026-03-27T09:11:30Z",
  "workspace_id": "4ce4d170-e6d5-4118-8f4d-fac69dc099ea"
}

{
  "duplicate": false,
  "accepted": 2,
  "errors": [],
  "batch_id": "b-2026-08-03T11:00:00Z-001",
  "robot_id": "0f9d1c2e-3b4a-4c5d-8e6f-7a8b9c0d1e2f"
}

{
  "completed_at": null,
  "delivery_state": "artifact_required",
  "error_message": null,
  "firmware_version": "3.3.0",
  "id": "5ed7cc57-e9a0-44b9-b345-8d8cc6ddf1aa",
  "inserted_at": "2026-03-27T09:12:00Z",
  "metadata": {},
  "robot_id": "d2c9a4df-c6ad-4016-9ba4-30c1c6d53a22",
  "rollback_version": null,
  "rollout": null,
  "rollout_percentage": 100,
  "scheduled_at": "2026-03-27T09:25:00Z",
  "status": "pending",
  "update_type": "firmware",
  "updated_at": "2026-03-27T09:14:00Z",
  "workspace_id": "4ce4d170-e6d5-4118-8f4d-fac69dc099ea"
}

{
  "current": {
    "coordinates": [
      44.8,
      41.7
    ],
    "location": {
      "lat": 41.7,
      "lng": 44.8
    },
    "observed_at": "2026-09-25T12:00:00.000000Z"
  },
  "geofence_states": [
    {
      "alert_id": null,
      "geofence_id": "6a05ee70-faa4-40f6-8f14-b49465c2d398",
      "geometry_revision": 1,
      "observed_at": "2026-09-25T12:00:00.000000Z",
      "safety_state": "safe",
      "state_revision": 1,
      "transition_version": 1790337600000000
    }
  ],
  "next_cursor": null,
  "samples": [
    {
      "coordinates": [
        44.8,
        41.7
      ],
      "id": "e8f77d1f-19af-4ded-91ab-b346058e7c31",
      "location": {
        "lat": 41.7,
        "lng": 44.8
      },
      "observed_at": "2026-09-25T12:00:00.000000Z",
      "received_at": "2026-09-25T12:00:01.000000Z",
      "robot_id": "6a05ee70-faa4-40f6-8f14-b49465c2d398"
    }
  ]
}