Cyborg Internal API spec

This document loosely specifies the API calls between the components of Cyborg. Driver, Agent, Conductor, and API endpoint.

These API’s are internal and therefore may change from version to version without warning or backwards compatibility. This document is kept as a developer reference to be edited before any internally braking changes are made.

Problem description

Developers writing one component of Cyborg need to know how to talk to another component of Cyborg, hopefully without having to go spelunking in the code of that component.

Use Cases

Happier Cyborg developers

Proposed change

Versioning internal API’s


A mess

Data model impact

A fixed internal API should help keep data models consistent.

REST API impact

The API changes add resource endpoints to:


  • POST start accelerator discovery FROM: Agent

  • GET get a list of discovered accelerators and their properties FROM: Agent


  • POST register driver FROM: Driver

  • POST start accelerator discovery across all drivers FROM: Conductor

  • GET get a list of all accelerators across all drivers FROM: Conductor

Conductor: * POST register agent FROM: Agent

The following new REST API call will be created:

Driver ‘POST /discovery’

Trigger the discovery and setup process for a specific driver

Content-Type: application/json


Driver ‘GET /hardware’

Gets a list of hardware, not accelerators, accelerators are ready to use entires available by the public API. Hardware are physical devices on nodes that may or may not be ready to use or even fully supported.

200 OK
Content-Type: application/json


Driver ‘POST /hello’

Registers that a driver has been installed on the machine and is ready to use. As well as it’s endpoint and hardware support.

Content-Type: application/json


Agent ‘POST /discovery’

Trigger the discovery and setup process for all registered drivers

See driver example

Agent ‘GET /hardware’

Get list of hardware across all drivers on the node

see driver example

Conductor ‘POST /hello’

Registers that an Agent has been installed on the machine and is ready to use.

Content-Type: application/json


Security impact

Care must be taken to secure the internal endpoints from malicious calls

Notifications impact


Other end user impact

This change might have an impact on python-cyborgclient

Performance Impact

In this model the Agent takes care of wrangling however many drivers are on a compute and the Conductor takes care of wrangling all the agents to present a coherent answer to the API quickly and easily. I don’t include API <-> Conductor calls yet because I assume the API will be for the most part working from the database while the Conductor tries to keep that database up to date and takes the occasional setup call.

Other deployer impact

In this model we won’t really know when we’re missing an agent. If one has reported in previously and then goes away we can have an alarm for that. But if an agent never reports in we just have to assume no instance exists by that name. This means making sure the Cyborg Drivers/Agent’s are installed and running is the responsibility of the deployment tool.

Developer impact

More internal communication in Cyborg



Primary assignee:


Other contributors:


Work Items






Documentation Impact






Release Name