Machine API

Reference guide for the virtual machine API.

Endpoint	Description
/api/machine/list	List machines by pubkey.
/api/machine/submit	Submit a new statement.
/api/machine/:vmid	Fetch a machine by ID.
/api/machine/:vmid/receipts	List receipts by machine.

---

Notice any mistakes, or something missing? Please let us know!
You can submit an issue here: Submit Issue

---

List Machines By Pubkey

Request a list of machines that are accessible by the token's pubkey.

Request Format

method   : 'GET'
endpoint : '/api/machine/list'
headers  : { 'Authorization' : 'Token ' + auth_token }

Response Interface

interface VMListResponse {
  data : {
    machines : MachineData[]
  }
}

Example Request

// Generate a request token.
const req = signer.machine.list()
// Deliver the request and token.
const res = await client.machine.list(req)
// Check the response is valid.
if (!res.ok) throw new Error(res.error)
// Unpack our data payload.
const { machines } = res.data

See the full code example here.

Related Interfaces

• MachineData

---

Submit a Witness Statement

Submit a witness statement to a virtual machine.

Request Format

method   : 'POST'
endpoint : '/api/machine/submit'
headers  : { 'content-type' : 'application/json' }
body     : JSON.stringify(submit_request)

Request Body

interface VMSubmitRequest {
  witness : WitnessData
}

Response Interface

export interface VMSubmitResponse {
  data : {
    receipt : WitnessReceipt
    vmdata  : MachineData
  }
}

Example Request

// Create a statement template.
const template = {
  action : 'close',
  method : 'endorse',
  path   : 'payout'
}
// Initialize a variable for our witness data.
let witness : WitnessData
// Alice signs the initial statement.
witness = a_signer.witness.create(vmstate, template)
// Bob endoreses the statement from Alice.
witness = b_signer.witness.endorse(vmstate, witness)
// Submit the signed statement to the server.
const res = await client.machine.submit(vmid, witness)
// Check the response is valid.
if (!res.ok) throw new Error(res.error)
// Unpack the data from the response.
const { receipt, vmdata } = res.data

See the full code example here.

Related Interfaces:

• MachineData
• WitnessReceipt

---

Read a Machine By ID

Fetch machine data from the server by its identifier (vmid).

Request Format

method   : 'GET'
endpoint : '/api/machine/:vmid'

Response Interface

export interface VMDataResponse {
  data : {
    vmdata : MachineData
  }
}

Example Request

// Fetch record from the server via id.
const res = await client.machine.read(vmid)
// Check the response is valid.
if (!res.ok) throw new Error(res.error)
// Unpack the data object.
const { vmdata } = res.data

See the full code example here.

Example Response

• MachineData

Related Interfaces

• MachineData

---

List Machine Receipts

Request all witness receipts for a virtual machine.

Request Format

method   : 'GET'
endpoint : '/api/machine/:vmid/receipts'

Response Interface

interface WitnessListResponse {
  data : {
    receipts : WitnessCommit[]
  }
}

Example Request

// Fetch a contract from the server by cid.
const res = await client.machine.commits(vmid)
// Check the response is valid.
if (!res.ok) throw new Error(res.error)
// Unpack the data object.
const { receipts } = res.data

See the full code example here.

Related Interfaces:

• WitnessReceipt