Robot API Reference & Registration Process

This document describes the cloud backend API contract for ToborVerse robots.

Server Information

• Live Base URL: http://54.219.152.130:5000

---

API Summary Table

Step	Endpoint Path	Method	Auth Headers Required	Content-Type	Request Body
1	/health	GET	None	N/A	None
2	/api/robots/register	POST	None	application/json	Registration Key & Device Metadata
3	/api/robots/verify	GET	Authorization: Bearer <API_KEY> X-Robot-ID: <ROBOT_ID>	N/A	None
4	/api/robots/heartbeat	POST	Authorization: Bearer <API_KEY> X-Robot-ID: <ROBOT_ID>	application/json	{}
5	/api/robots/reset	PATCH	Authorization: Bearer <API_KEY> X-Robot-ID: <ROBOT_ID>	N/A	None
6	/api/robots/unregister	POST / PATCH	Authorization: Bearer <API_KEY> X-Robot-ID: <ROBOT_ID>	application/json	{}

---

Endpoint Details

1. Check Backend Health

Verifies system availability and dependency health (database, storage layers).

• HTTP Method: GET
• URL: http://54.219.152.130:5000/health
• Headers: None
• Request Body: None

Response (200 OK)

{
  "success": true,
  "status": 200,
  "message": "All services are healthy",
  "timestamp": "2026-09-22T10:00:00.000Z",
  "checks": [
    {
      "name": "database",
      "ok": true,
      "message": "Database connected successfully"
    },
    {
      "name": "s3",
      "ok": true,
      "message": "S3 client configured successfully"
    },
    {
      "name": "app",
      "ok": true,
      "message": "Core routes are registered"
    }
  ]
}

---

2. Register Robot

Exchanges a provisioned registration key and device hardware parameters for a Robot ID and persistent API Key.

• HTTP Method: POST
• URL: http://54.219.152.130:5000/api/robots/register
• Headers:
• Content-Type: application/json
• Request Body:

  {
    "registerKey": "tv_rrt_...",
    "device": {
      "serialNo": "1424325095622",
      "robotModel": "NVIDIA Jetson Orin NX",
      "firmwareVersion": "1.2.3",
      "machineId": "5dbfb12414a3456d9014d88183e338b1",
      "osRelease": "PRETTY_NAME=\"Ubuntu 22.04.5 LTS\"\n"
    }
  }
  

  Note: Any optional device field that is not populated should be omitted rather than sent as an empty string.

Response (200 OK)

{
  "status": 200,
  "success": true,
  "message": "Robot registered successfully",
  "robotDetails": {
    "id": "01a07b65-d671-799b-9481-92bceb8d3a75",
    "apiKey": "tv_robot_...",
    "status": "connected"
  },
  "data": {
    "id": "01a07b65-d671-799b-9481-92bceb8d3a75",
    "credential": "tv_robot_...",
    "status": "connected"
  }
}

Error Responses

• 400 Bad Request: Registration key missing, expired, invalid, or robot already registered.

---

3. Verify Credential

Checks that the stored Robot ID and API Key are valid and accepted by the cloud backend.

• HTTP Method: GET
• URL: http://54.219.152.130:5000/api/robots/verify
• Headers:
• Authorization: Bearer <API_KEY>
• X-Robot-ID: <ROBOT_ID>
• Request Body: None

Response Headers

X-Robot-ID: 01a07b65-d671-799b-9481-92bceb8d3a75

Response (200 OK)

{
  "status": 200,
  "success": true,
  "message": "Credential accepted"
}

Error Responses

• 401 Unauthorized: Missing or invalid Authorization or X-Robot-ID header.

---

4. Send Heartbeat

Periodic liveness check sent by active robots to signal online availability.

• HTTP Method: POST
• URL: http://54.219.152.130:5000/api/robots/heartbeat
• Headers:
• Authorization: Bearer <API_KEY>
• X-Robot-ID: <ROBOT_ID>
• Content-Type: application/json
• Request Body:

  {}
  

Response Headers

X-Robot-ID: 01a07b65-d671-799b-9481-92bceb8d3a75

Response (200 OK)

{
  "status": 200,
  "success": true,
  "message": "heartbeat checked successfully"
}

Error Responses

• 401 Unauthorized: Invalid API Key or unknown Robot ID.

---

5. Reset Robot API Key

Rotates the persistent API Key for an existing robot.

• HTTP Method: PATCH
• URL: http://54.219.152.130:5000/api/robots/reset
• Headers:
• Authorization: Bearer <API_KEY>
• X-Robot-ID: <ROBOT_ID>
• Request Body: None

Response Headers

X-Robot-ID: 01a07b65-d671-799b-9481-92bceb8d3a75

Response (200 OK)

{
  "status": 200,
  "success": true,
  "message": "Robot reset successfully",
  "robotDetails": {
    "id": "01a07b65-d671-799b-9481-92bceb8d3a75",
    "apiKey": "tv_robot_newkey...",
    "status": "connected"
  },
  "data": {
    "robot": {
      "id": "01a07b65-d671-799b-9481-92bceb8d3a75",
      "status": "connected"
    },
    "credential": "tv_robot_newkey..."
  }
}

Error Responses

• 401 Unauthorized: Invalid authentication credentials.
• 403 Forbidden: Mismatched API key.

---

6. Unregister / Delete Robot

Revokes the persistent API Key and removes the robot record from the cloud backend.

• HTTP Method: POST or PATCH
• URL: http://54.219.152.130:5000/api/robots/unregister
• Headers:
• Authorization: Bearer <API_KEY>
• X-Robot-ID: <ROBOT_ID>
• Content-Type: application/json
• Request Body:

  {}
  

Response Headers

X-Robot-ID: 01a07b65-d671-799b-9481-92bceb8d3a75

Response (200 OK)

{
  "status": 200,
  "success": true,
  "message": "Robot unregistered successfully"
}

Error Responses

• 400 Bad Request: Robot not found or cannot be unregistered.
• 401 Unauthorized: Missing or invalid credentials.
• 403 Forbidden: Invalid API key for the specified Robot ID.

---

Common Error Status Codes

Status Code	Meaning	Cause / Action
400 Bad Request	Invalid Request	Missing required body parameters, expired registration key, or unregister error.
401 Unauthorized	Authentication Failed	Missing or invalid Authorization header or X-Robot-ID header.
403 Forbidden	Access Forbidden	Current API key does not match the record for the given Robot ID.
500 Internal Error	Server Error	Database failure or unexpected backend exception.
503 Unavailable	Service Unhealthy	Dependency check failure during /health probe.