Skip to main content

API

This is the back-end API of the portal. It allows authenticated users to get basic information about devices running on their account. For more advanced use-cases please use the SDK instead.

The base URL of the API is /@transitive-robotics/_robot-agent/api/v1/.

Authentication​

All request need to bear an Authorization header bearing a JWT signed with the users JWT secret, containing the following payload:

{
   userId, // (string) The userId of the bearer
   api // (number) The api version (currently 1)
}

Example Request​

An example request against the API running on the official transitiverobotics.com portal:

$ curl -H "Authorization: Bearer XXX.YYY.ZZZ" https://portal.transitiverobotics.com/@transitive-robotics/_robot-agent/api/v1/running/
{"d_f5b1b62bd4":{"@transitive-robotics":{"terminal":{"0.2.11":"0.2.11"},"test":{"0.3":"0.3.2"}}},"d_31efbefa35":{"@transitive-robotics":{"webrtc-video":{"0.16.1":false,"0.16.2":"0.16.2"}}}}

Endpoints​

GET running​

Get all devices and the capabilities they are running, e.g.:

{
  "d_f5b1b62bd4": {
    "@transitive-robotics": {
      "terminal": {
        "0.2.11": "0.2.11"
      },
      "test": {
        "0.3": "0.3.2"
      }
    }
  },
  "d_31efbefa35": {
    "@transitive-robotics": {
      "webrtc-video": {
        "0.16.1": false,
        "0.16.2": "0.16.2"
      }
    }
  }
}

GET running/:deviceId​

Get all capabilities running on the specified device, e.g.:

{
  "@transitive-robotics": {
    "terminal": { "0.2.11": "0.2.11" },
    "test": { "0.3": "0.3.2" }
  }
}

GET heartbeats​

Get list of all devices together with their heartbeats, e.g.:

{
  "d_f5b1b62bd4": "2023-12-28T01:49:45.235Z",
  "d_31efbefa35": "2023-12-06T22:40:54.739Z",
  "d_82ab3aeb35": "2023-12-26T16:27:12.401Z"
}

GET info​

Get list of all devices with their basic info, e.g.:

{
  "d_f5b1b62bd4": {
    "os": {
      "hostname": "homedesk",
      "release": "5.15.0-91-generic",
      "version": "#101~20.04.1-Ubuntu SMP Thu Nov 16 14:22:28 UTC 2023",
      "networkInterfaces": {
        "lo": [
          {
            "address": "127.0.0.1",
            "netmask": "255.0.0.0",
            "family": "IPv4",
            "mac": "00:00:00:00:00:00",
            "internal": true,
            "cidr": "127.0.0.1/8"
          }
        ],
        "enp6s0": [
          {
            "address": "192.168.1.26",
            "netmask": "255.255.255.0",
            "family": "IPv4",
            "mac": "3c:7c:3f:25:bd:46",
            "internal": false,
            "cidr": "192.168.1.26/24"
          }
        ],
        "br-a12fa758586d": [
          {
            "address": "172.20.0.1",
            "netmask": "255.255.0.0",
            "family": "IPv4",
            "mac": "02:42:5e:37:0d:29",
            "internal": false,
            "cidr": "172.20.0.1/16"
          }
        ]
      },
      "lsb_release": "LSB Version:\tcore-11.1.0ubuntu2-noarch:security-11.1.0ubuntu2-noarch\nDistributor ID:\tUbuntu\nDescription:\tUbuntu 20.04.6 LTS\nRelease:\t20.04\nCodename:\tfocal",
      "lsb": {
        "LSB Version": "core-11.1.0ubuntu2-noarch:security-11.1.0ubuntu2-noarch",
        "Distributor ID": "Ubuntu",
        "Description": "Ubuntu 20.04.6 LTS",
        "Release": "20.04",
        "major": 20,
        "minor": 4,
        "Codename": "focal"
      },
      "dpkgArch": "amd64"
    },
    "config": {
      "global": {
        "rosReleases": null
      }
    },
    "rosReleases": [
      "galactic",
      "noetic"
    ]
  },
  "d_d92bf6e84e": {...}
}

Note that the content of this may change in the future.

POST rpc/:deviceId/:command [ARGUMENTS]​

Call the specified agent command on the given device, e.g.:

POST rpc/d_superbot123/restartPackage '{"pkg":"@transitive-robotics/webrtc-video"}'

Currently the agent exposes these commands:

  • ping: ping the agent. Returns {"result": TIME_ON_DEVICE} when successful, where TIME_ON_DEVICE is milliseconds since the epoch (1970).
  • restart: Restart the agent.
  • stopAll: Stop all capabilities.
  • restartPackage {pkg}: Restart the given package (provided in JSON), e.g.: 
    POST rpc/d_superbot123/restartPackage '{"pkg":"@transitive-robotics/webrtc-video"}'
  • startPackage {pkg}: Start the given package. Does nothing if it is already running.
  • stopPackage {pkg}: Stop the given package.
  • getPkgLog {pkg}: Get the given package's log (zip compressed, base64 encoding).