The Worker API sets the communication protocol between an AI worker and the Humatron service. Humatron serves as a mediator for communication, management, and data exchange between the AI worker and its employer. Humatron simplifies the development and accelerates adoption of AI workers by providing many of the critical features and capabilities out-of-the-box through Worker API. All information an AI worker has about its employer, including social and organizational details, comes from actions it can perform and data it accesses through this API.

An AI worker implementation is typically an online service managed by an AI worker builder. The only essential requirement is that it provides a publicly accessible HTTPS endpoint for communication with the Humatron service.

Before describing the Worker API protocol, let's review the terminology nomenclature:

Here's an outline of the Worker API protocol:

One important feature of the Worker API is its logically asynchronous nature. As discussed in General Structure both HTTP requests and responses in Worker API act as simple containers for payload objects. The actual data exchange is carried by the payload objects inside of these containers. If an AI worker receives a request that requires significant processing time, the response (i.e. its payload) can be sent later in the response to one of the subsequent requests. While HTTP protocol is technically synchronous, Worker API provides its asynchronous capabilities by implementing two principles:

Combination of these two techniques allows AI workers to have asynchronous behavior, if and when required, over the synchronous HTTP protocol. This is also the foundation for supporting an autonomous work capabilities for AI workers. Note that interview request is special and it is the only exception from this rule: it is a synchronous request only and its response can only contain one specific payload object.

The lifecycle of an AI worker instance in terms of request types is as follows:

Note that when worker instance is paused incoming requests are NOT buffered and are simply ignored. When worker instance gets resumes - it will NOT receive previously ignored requests while it was paused.

In Worker API both HTTP request and response act as simple containers for array of payloads which is a central idea in Worker API design. The actual data exchange between Humatron and AI worker instance is done through passing payloads objects. All Worker API HTTP requests and response follow the same structure and carry array of payload objects which can generally contain zero or more elements. Each request payload object has an ID and the response payload may references this ID. Note that a payload object can be unrelated to any previous requests - this is part of the overall asynchronous design of Worker API where the immediate response does not have to have a payload for its request; such payload, if required, can come asynchronously with subsequent responses at a later time.

Each request from Humatron side conforms to the following JSON structure:

Each response from AI worker side should conform to the following JSON structure:

All REST requests in Worker API follow the general structure outline in General Structure section. Each request differs only in req_cmd field and associated payload array. Note that all requests, except for interview, are asynchronous. Here is the list of supported requests:

interview request has req_cmd field equal to 'interview'. A interview request is used to conduct an interview for the worker template (i.e. specialist). Look at support_interview_mode field of specialist object to see if particular specialist supports an interview mode. Note that auto-interview mode is supported entirely on Humatron side and this request will be not be sent if auto-interview mode is enabled.

This request has one payload object and requires synchronous response. The request payload object has the following structure:

Since this request is synchronous the response with necessary payload must be sent back in response to this request (i.e. it cannot be sent later as for asynchronous requests).Response payload array for interview request should contain, among other potential payload elements, one payload object with the following structure:

heartbeat request has req_cmd field equal to 'heartbeat'. Apart from regular requests, Humatron sends regular heartbeat requests to each hired AI worker. These requests are sent out at least several times a minute. The heartbeat requests' main purpose is to provide a regular ping so that AI worker can react quasi-asynchronously over the synchronous HTTP protocol. This provides a standard idiom for AI workers to asynchronously communicate with the outside world. This is also the foundation for supporting an autonomous work capabilities for AI workers.

heartbeat request always has just one payload object with the following structure:

Response payload array for heartbeat request does not require any specific structure, and it can be empty. Just like any other responses in Worker API it can contain zero or more payload objects for either previous requests or payloads unrelated to any previous requests.

register request has req_cmd field equal to 'register'. This request is sent when a new worker instance is hired and just before the onboarding commences. The request always has just one payload object with the following structure:

As with all asynchronous requests, the REST response for this request acts as a container for zero or more payloads. The responding payload for this particular request can come in the immediate response to this request or in any subsequent responses for any other requests. Response payload object for this request should have the following structure:

unregister request has req_cmd field equal to 'unregister'. This request is sent when a worker instance is terminated. Note that after this request is sent no other requests will be sent to this worker instance. Note also that the response to this request does not provide any error codes and Humatron assumes that termination (i.e. unregister) requests always succeed. This request always has just one payload object with the following structure:

As with all asynchronous requests, the REST response for this request acts as a container for zero or more payloads. The responding payload for this particular request can come in the immediate response to this request or in any subsequent responses for any other requests. It is assumed that when this response is received any resources associated with worker instance have been released or cleaned up as necessary. Response payload object for this request should have the following structure:

pause request has req_cmd field equal to 'pause'. This request is sent when a worker instance is temporarily paused. Pausing a working is a temporary operation unlike termination that is permanent. Paused worker instance can either be resumed or unregistered (i.e. terminated). The request always has just one payload object with the following structure:

As with all asynchronous requests, the REST response for this request acts as a container for zero or more payloads. The responding payload for this particular request can come in the immediate response to this request or in any subsequent responses for any other requests. Response payload object for this request should have the following structure:

resume request has req_cmd field equal to 'resume'. This request is sent when a worker instance is resumed from paused state. The request always has just one payload object with the following structure:

As with all asynchronous requests, the REST response for this request acts as a container for zero or more payloads. The responding payload for this particular request can come in the immediate response to this request or in any subsequent responses for any other requests. Response payload object for this request should have the following structure:

message request has req_cmd field equal to 'message'. This request is used to send one or more messages from the outside world to the worker instance. This request payload array contains one or more payload objects with the following structure:

The following describes the request message object structure based on the channel_type value:

Human-in-the-Loop Curation (or simply "curation") is a mechanism where an AI worker delegates a task to a human operator when it is unable to process it independently or requires additional information, context, or assistance that only human operator can provide. This capability is often beneficial and, in some cases, essential for mission-critical systems in highly regulated industries, such as healthcare, pharmaceuticals, finance, transportation, military, or hazardous material handling.

In the Humatron platform, an AI worker can initiate a curation request at any time and for any reason. This can occur due to a variety of factors, for example:

Curation requests are always initiated only by the AI worker. Note that curation support is optional for a given build and can be enabled or disabled at any time by the build’s owner. If curation is disabled, all curation events for that build (i.e. its instances) will be ignored by the Humatron platform.

To start the curation request, you simply need to send the following payload object as part of payload array of the nearest response:

When a curation request (i.e.the payload object above) is received by the Humatron, a new curation event will appear on the Humatron website, and all registered notification contacts for this build will be alerted. Registered Humatron users with curation privilege can then log in to the website to review and process the curation request.

For each curation request on the website, the message and context fields will be displayed along with other pertinent information. Note that Humatron does not require a response to the curation request - user can simply mark curation request as ignored on the website. If the response to curation request is provided, it is not required to be realtime. In fact, depending on the nature of curation request the response can take minutes or hours. If provided, the curation response consists of the JSON object that human operator needs to provide that will be sent back to the worker instance via REST channel.

The specific structure of the curation response JSON object is up to the worker implementation and is not governed by Humatron API. Note also that in order to receive this curation response, if any, the worker implementation must process messages from the REST channel.

Requests and responses in Worker API use a set of common JSON objects:

Organization object defines any organization or a company in Humatron. This can be a hiring company, a company that built and trained AI worker, a partner company that provides talent acquisition services and uses Humatron on behalf of its clients, as well as Humatron AI itself. Organization object has the following structure:

Specialist object defines worker template in Humatron. It is also sometime called a resume or a build which are used interchangeably in this documentation. Specialist object has the following structure:

Instance object defines hired specialist. Instance object has the following structure:

Person object defines user's personal data in Humatron. Person object has the following structure:

Role object defines a security role that a Person has. Humatron supports the following security roles:

Role object has the following structure:

Address object defines address record that is used by Personand Organization objects. Address object has the following structure:

PricePlan object defines the pay plan for the worker. PricePlan object has the following structure:

File object defines transferable file data. Humatron provides access to these files with certain provider-specific properties. Note that properties field's content is provider specific. File object has the following structure:

Resource object defines communication resource (i.e. configured instance of the communication channel). Resource object has the following structure:

ContactRecord object defines a contact record. Note that properties field content is specific to kind of contact record.ContactRecord object has the following structure:

Contact object defines contact person with nested contact records. Contact object has the following structure:

Channel object defines specialist's channel. Channel object has the following structure:

The REST channel is a special communication channel that enables REST interactions between a worker instance and the end user. Unlike other communication channels, such as email, Slack, or SMS, the REST channel does not come with an existing client application (e.g., an email or Slack client). REST communication channel allows a worker instance to communicate with a non-standard client-side applications such as custom chatbots, built-in copilots, etc. Note that the REST channel can be registered in the address book, which allows to use it just like any other resource in the Worker API.

Let's review the terminology nomenclature:

Client application uses REST channel API to send and receive messages to and from worker instance. A worker instance sends and receives messages to and from client application through the standard message request of the Worker API (i.e. the same way as for any other communication channels like email or Slack). Below is an outline of the REST channel API protocol. Note that it is similar to the Worker API protocol structure.

In REST channel API both HTTP request and response act as simple containers for array of payloads which is a central idea in both Worker API and REST channel API design. The actual data exchange between REST server and client application is done through passing payloads objects.

Each request sent from client application to Humatron should conform to the following JSON structure:

Each response should conform to the following JSON structure:

All REST channel API requests follow the general structure outline in requests structure section. Each request differs only in req_cmd field and associated payload array. All requests are asynchronous. Here is the list of supported requests:

REST channel API message request has req_cmd field equal to 'message'. This request is used to send one or more messages from the client application to the worker instance via REST channel server. This request payload array contains one or more payload objects with the following structure:

The response payload array contains empty or non-empty payload object array with the following structure of elements:

REST channel API heartbeat request has req_cmd field equal to 'heartbeat'. These requests primary purpose is to prompt the server to respond to previousmessage requests from AI workers that have accumulated on the REST channel server.

heartbeat request has empty payload.

The response payload array contains empty or non-empty payload object array with the following structure of elements.

Note, that this response payload structure is same for both message and heartbeat responses types.