API Services

Web Socket communication

The Machinations API is based on socket.io. Our API accepts & returns JSON-encoded request/responses and uses the WebSocket Protocol. The API is in active development, and we’re always gathering feedback, looking for new use cases.

Behind the API there is a software layer connecting your Machinations Public Diagrams to allow your socket.io client to get diagram changes.

You can use any web socket client compatible with socket.io. Below, you can find examples for NodeJS. Our C# Unity Plugin, for example, features a full implementation of the Machinations API and it uses WebSocketSharp


You need to copy your User Key from your Machinations account, under your Profile Picture > Settings > Account Details.

Keep your credentials secure! Do not share your secret API keys in publicly accessible spaces such as GitHub, client-side code, and so forth. All requests must be made over WSS (WebSocket Secure). Calls made over plain WS will fail. API requests without the User Key will also fail.

Provide your User Key as a parameter of connection to Machinations. You do not need to provide a password. Instead, you will need to provide a Diagram Token. You can obtain this by clicking on the Diagram’s title…

And then pressing the Generate Token button. Copy the token and use it with the code below.

This is a fully functional connection example in NodeJS


C# (specific to Unity Socket IO Component)

In case of an invalid User Key, the client receives an error response and the connection is terminated.

Through the authenticated socket, clients can send/receive messages using the JSON format.

Connection to the Machinations Diagram

Make sure you handle the following Machinations responses:

  • deny response: 
  • success response 

Message format: JSON-schema

Connect Diagram Elements

From your Machinations diagram, get the Node ID and properties from the Properties Panel, by selecting the Node.

Based on the Node ID & Properties, the client is able to gate the current value & changes of properties during diagram edit.

Initialization request

The initialization request can be sent at any time and the communication list will be changed.

Example: node.js

  • Machinations will respond with the properties values: 

Example: node.js

Example: JSON-schema response

  • While the socket is open, the client will receive, from Machinations, any properties changes but only the ones reflected on the init list.

Example: node.js

Example: JSON-schema response

Communication Node & Properties List

  • An array of elements (node id & properties) set up at initialization request (‘game-init’)
  • The client will receive a property update (‘diagram-elements-updated’ event type) only if the property(& node id) is on the list  
  • This list can be changed with an initialization request (‘game-init’), at any time

Example of a JSON-schema

Sending values to Machinations

You use the game-update-diagram-elements event to send values to Machinations. The message should respect the following format:

Named versions

This request asks for the list of named versions for a diagram. The diagram will be identified by diagramToken.

The response has the following format:

Get all diagram elements

This request asks for a list of all elements in a diagram. The diagram will be identified by diagramToken.

The response has the following format:

Events types

  • Send  (socket.emit …)
    •  ‘api-authorize’ – Authorizing diagram connection 
    •  ‘game-init’ – Request Nodes properties from a diagram
    • ‘get-versions’ – Request version history from a diagram.
  • Receive (socket.on …)
    • api-auth-deny’ – Authorization denied. You do not have a valid Token or user has no rights (user is identified based on the User Key)
    • ‘api-auth-success’ – Successful authorization   
    • ‘game-init’ – Response at initialization request 
    • ‘diagram-elements-updated’ – Sent when an element from the communication list is changed on machinations.io‘s side
    • ‘api-error’ – Machinations API error 
    • ‘error’ – Socket.io error

Available Properties 

Error Codes:

  • 415050 – Invalid or missing User Key
  • 415051 – Error while validating User Key
  • 415070 – Missing diagram Token
  • 415071 – Invalid diagram Token
  • 415072 – Error during validating diagram Token
  • 415073 – Parameter diagramToken not present in the JSON request
  • 415090 – Web socket not authenticated
  • 415091 – Web socket not authorized 
  • 4150110 – Diagram parse error
  • 415130 – Parameter gameData not present in the JSON request
  • 415131 – Parameter machinationsIDs not present in the JSON request