Create a start state

curl --request POST \
  --url https://guidinghand.ai/v1/start_states \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "from": "<string>",
  "script": "<string>",
  "instruction": "<string>",
  "agent_id": "default",
  "description": "<string>",
  "metadata": {
    "customer_id": "cus_42"
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    from: '<string>',
    script: '<string>',
    instruction: '<string>',
    agent_id: 'default',
    description: '<string>',
    metadata: {customer_id: 'cus_42'}
  })
};

fetch('https://guidinghand.ai/v1/start_states', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://guidinghand.ai/v1/start_states"

payload = {
    "name": "<string>",
    "from": "<string>",
    "script": "<string>",
    "instruction": "<string>",
    "agent_id": "default",
    "description": "<string>",
    "metadata": { "customer_id": "cus_42" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "object": "start_state",
  "start_state_id": "ss_0aQ3Vb7sT2Lc",
  "kind": "image",
  "name": "Printer offline",
  "description": "<string>",
  "from": "win10-22h2",
  "method": "hand",
  "script": "<string>",
  "instruction": "<string>",
  "agent_id": "<string>",
  "task_id": "<string>",
  "status": "building",
  "version": 123,
  "os": "windows",
  "labels": [
    "vm"
  ],
  "runner_id": "<string>",
  "error": "<string>",
  "view": {
    "screen_url": "<string>",
    "input_url": "<string>",
    "expires_at": "2023-11-07T05:31:56Z"
  },
  "metadata": {
    "customer_id": "cus_42"
  },
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "code": "<string>",
    "answered_by": "customer",
    "test_case_ids": [
      "<string>"
    ]
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "code": "<string>",
    "answered_by": "customer",
    "test_case_ids": [
      "<string>"
    ]
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "code": "<string>",
    "answered_by": "customer",
    "test_case_ids": [
      "<string>"
    ]
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "code": "<string>",
    "answered_by": "customer",
    "test_case_ids": [
      "<string>"
    ]
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "code": "<string>",
    "answered_by": "customer",
    "test_case_ids": [
      "<string>"
    ]
  }
}

Start states

Create a start state

Makes a machine from from on a runner that has it. With script, the script runs and the machine is saved (building, then ready or failed). With instruction, a GuidingHand task sets it up (linked in task_id), then it’s saved. With neither (method: hand), the machine stays open for someone to set up by hand: watch it with /screen, drive it with /input, then /save. start_state.ready or start_state.failed is sent when it’s done. Needs the admin role or an API key.

POST

start_states

curl --request POST \
  --url https://guidinghand.ai/v1/start_states \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "from": "<string>",
  "script": "<string>",
  "instruction": "<string>",
  "agent_id": "default",
  "description": "<string>",
  "metadata": {
    "customer_id": "cus_42"
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    from: '<string>',
    script: '<string>',
    instruction: '<string>',
    agent_id: 'default',
    description: '<string>',
    metadata: {customer_id: 'cus_42'}
  })
};

fetch('https://guidinghand.ai/v1/start_states', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://guidinghand.ai/v1/start_states"

payload = {
    "name": "<string>",
    "from": "<string>",
    "script": "<string>",
    "instruction": "<string>",
    "agent_id": "default",
    "description": "<string>",
    "metadata": { "customer_id": "cus_42" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "object": "start_state",
  "start_state_id": "ss_0aQ3Vb7sT2Lc",
  "kind": "image",
  "name": "Printer offline",
  "description": "<string>",
  "from": "win10-22h2",
  "method": "hand",
  "script": "<string>",
  "instruction": "<string>",
  "agent_id": "<string>",
  "task_id": "<string>",
  "status": "building",
  "version": 123,
  "os": "windows",
  "labels": [
    "vm"
  ],
  "runner_id": "<string>",
  "error": "<string>",
  "view": {
    "screen_url": "<string>",
    "input_url": "<string>",
    "expires_at": "2023-11-07T05:31:56Z"
  },
  "metadata": {
    "customer_id": "cus_42"
  },
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "code": "<string>",
    "answered_by": "customer",
    "test_case_ids": [
      "<string>"
    ]
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "code": "<string>",
    "answered_by": "customer",
    "test_case_ids": [
      "<string>"
    ]
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "code": "<string>",
    "answered_by": "customer",
    "test_case_ids": [
      "<string>"
    ]
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "code": "<string>",
    "answered_by": "customer",
    "test_case_ids": [
      "<string>"
    ]
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "code": "<string>",
    "answered_by": "customer",
    "test_case_ids": [
      "<string>"
    ]
  }
}

Authorizations

Authorization

string

header

required

An org API key (gh_live_…) from Settings → API keys in the console.

Body

application/json

With script, the runner boots from, runs it and saves the machine. With instruction, a GuidingHand task with that prompt sets it up, then it’s saved. With neither, the machine boots and stays open for someone to set it up by hand.

name

string

required

Required string length: 1 - 200

from

string

required

An image (e.g. win10-22h2) or a start state to start from.

script

string

Runs elevated, as the signed-in user.

Maximum string length: 100000

instruction

string

A prompt for a GuidingHand task that sets the machine up.

Maximum string length: 8000

agent_id

string

default:default

The agent for instruction.

description

string

metadata

object

Your own ids and labels (e.g. a ticket or customer id), returned as given.

Show child attributes

Example:

{ "customer_id": "cus_42" }

Response

A machine to start each try from: a runner’s base OS install (kind: image, read-only, every org sees it) or a saved machine made from one (kind: state).

object

any

start_state_id

string

Example:

"ss_0aQ3Vb7sT2Lc"

kind

enum<string>

Available options:

image,

state

name

string

Example:

"Printer offline"

description

string

from

string | null

The image or start state it was made from (null for an image).

Example:

"win10-22h2"

method

enum<string> | null

How it was set up: by hand on its open machine, by a script, or by a GuidingHand task.

Available options:

hand,

script,

instruction,

null

script

string | null

instruction

string | null

agent_id

string | null

The agent that ran the instruction.

task_id

string | null

With method: instruction: the task that set it up.

status

enum<string>

building: its script or instruction is running. open: its machine is running for someone to set up or look at. saving, then ready. failed: see error.

Available options:

building,

open,

saving,

ready,

failed

version

integer

Goes up by one with each save; 0 until first saved. A test run uses the version current when it was created.

string

Example:

"windows"

labels

string[]

Where it can run: its runner’s labels.

Example:

["vm"]

runner_id

string | null

The runner that holds its disk (null for an image: any runner that has it).

error

string | null

view

object | null

While its machine is open.

Show child attributes

metadata

object

Your own ids and labels (e.g. a ticket or customer id), returned as given.

Show child attributes

Example:

{ "customer_id": "cus_42" }

created_at

string<date-time> | null

updated_at

string<date-time> | null