Open a start state

curl --request POST \
  --url https://guidinghand.ai/v1/start_states/{start_state_id}/open \
  --header 'Authorization: Bearer <token>'

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

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

import requests

url = "https://guidinghand.ai/v1/start_states/{start_state_id}/open"

headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, 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>"
    ]
  }
}

POST

start_states

{start_state_id}

open

Open a start state

curl --request POST \
  --url https://guidinghand.ai/v1/start_states/{start_state_id}/open \
  --header 'Authorization: Bearer <token>'

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

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

import requests

url = "https://guidinghand.ai/v1/start_states/{start_state_id}/open"

headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, 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>"
    ]
  }
}

Authorizations

Authorization

string

header

required

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

Path Parameters

start_state_id

string

required

The start state’s id (ss_…), or an image’s id (e.g. win10-22h2).

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