Add or change procedures
curl --request POST \
--url https://guidinghand.ai/v1/agents/{agent_id}/procedures/batch \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"procedures": [
{
"id": "<string>",
"revision": 123,
"title": "<string>",
"use_when": "<string>",
"inputs": [
{
"name": "<string>",
"type": "text",
"description": "<string>",
"required": true,
"options": [
"<string>"
],
"example": "<string>"
}
],
"goal": "<string>",
"context": "<string>",
"instructions": "<string>",
"steps": [
"<string>"
],
"checks": "<string>",
"body": "<string>",
"tools": [
"<string>"
],
"approval": {
"required": true,
"by": "anyone",
"who": "",
"covers": [],
"note": ""
},
"category": "<string>",
"test_cases": [
{
"name": "Apps switched to dark mode",
"prompt": "All my windows suddenly went black. How do I get the white back?",
"key": "DSP-01",
"start_state": "win10-22h2",
"setup_script": "<string>",
"success": {
"check_script": "<string>",
"rubric": "<string>"
},
"customer": {
"persona": "Retired teacher. Not technical. Short, polite answers.",
"facts": {
"Wi-Fi network": "HomeNet",
"Wi-Fi password": {
"secret": "blue-kite-42"
}
},
"clicks_admin_prompts": true,
"does_steps": true
},
"operator": {},
"limits": {
"minutes": 10,
"steps": 250
},
"runs_on": "vm",
"category": "Display & graphics",
"tags": [
"uac"
],
"metadata": {
"customer_id": "cus_42"
},
"must_visit": [
"support.example.com|docs.example.com"
],
"expected": "<string>",
"messages": [
"<string>"
],
"start_url": "<string>",
"procedure_id": "prc_4mJx0aQe1",
"inputs": [
{
"mtm": "20XW",
"region": "UK"
},
{
"mtm": "21DE",
"region": "US"
}
],
"objects": [
"<string>"
]
}
]
}
],
"test_set_id": "<string>"
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
procedures: [
{
id: '<string>',
revision: 123,
title: '<string>',
use_when: '<string>',
inputs: [
{
name: '<string>',
type: 'text',
description: '<string>',
required: true,
options: ['<string>'],
example: '<string>'
}
],
goal: '<string>',
context: '<string>',
instructions: '<string>',
steps: ['<string>'],
checks: '<string>',
body: JSON.stringify('<string>'),
tools: ['<string>'],
approval: {required: true, by: 'anyone', who: '', covers: [], note: ''},
category: '<string>',
test_cases: [
{
name: 'Apps switched to dark mode',
prompt: 'All my windows suddenly went black. How do I get the white back?',
key: 'DSP-01',
start_state: 'win10-22h2',
setup_script: '<string>',
success: {check_script: '<string>', rubric: '<string>'},
customer: {
persona: 'Retired teacher. Not technical. Short, polite answers.',
facts: {'Wi-Fi network': 'HomeNet', 'Wi-Fi password': {secret: 'blue-kite-42'}},
clicks_admin_prompts: true,
does_steps: true
},
operator: {},
limits: {minutes: 10, steps: 250},
runs_on: 'vm',
category: 'Display & graphics',
tags: ['uac'],
metadata: {customer_id: 'cus_42'},
must_visit: ['support.example.com|docs.example.com'],
expected: '<string>',
messages: ['<string>'],
start_url: '<string>',
procedure_id: 'prc_4mJx0aQe1',
inputs: [{mtm: '20XW', region: 'UK'}, {mtm: '21DE', region: 'US'}],
objects: ['<string>']
}
]
}
],
test_set_id: '<string>'
})
};
fetch('https://guidinghand.ai/v1/agents/{agent_id}/procedures/batch', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://guidinghand.ai/v1/agents/{agent_id}/procedures/batch"
payload = {
"procedures": [
{
"id": "<string>",
"revision": 123,
"title": "<string>",
"use_when": "<string>",
"inputs": [
{
"name": "<string>",
"type": "text",
"description": "<string>",
"required": True,
"options": ["<string>"],
"example": "<string>"
}
],
"goal": "<string>",
"context": "<string>",
"instructions": "<string>",
"steps": ["<string>"],
"checks": "<string>",
"body": "<string>",
"tools": ["<string>"],
"approval": {
"required": True,
"by": "anyone",
"who": "",
"covers": [],
"note": ""
},
"category": "<string>",
"test_cases": [
{
"name": "Apps switched to dark mode",
"prompt": "All my windows suddenly went black. How do I get the white back?",
"key": "DSP-01",
"start_state": "win10-22h2",
"setup_script": "<string>",
"success": {
"check_script": "<string>",
"rubric": "<string>"
},
"customer": {
"persona": "Retired teacher. Not technical. Short, polite answers.",
"facts": {
"Wi-Fi network": "HomeNet",
"Wi-Fi password": { "secret": "blue-kite-42" }
},
"clicks_admin_prompts": True,
"does_steps": True
},
"operator": {},
"limits": {
"minutes": 10,
"steps": 250
},
"runs_on": "vm",
"category": "Display & graphics",
"tags": ["uac"],
"metadata": { "customer_id": "cus_42" },
"must_visit": ["support.example.com|docs.example.com"],
"expected": "<string>",
"messages": ["<string>"],
"start_url": "<string>",
"procedure_id": "prc_4mJx0aQe1",
"inputs": [
{
"mtm": "20XW",
"region": "UK"
},
{
"mtm": "21DE",
"region": "US"
}
],
"objects": ["<string>"]
}
]
}
],
"test_set_id": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"object": "list",
"data": [
{
"object": "procedure",
"id": "prc_…",
"agent_id": "<string>",
"title": "<string>",
"use_when": "<string>",
"inputs": [
{
"name": "<string>",
"type": "text",
"description": "<string>",
"required": true,
"options": [
"<string>"
],
"example": "<string>"
}
],
"goal": "<string>",
"context": "<string>",
"instructions": "<string>",
"steps": [
{
"id": "<string>",
"text": "<string>",
"subprocedure": {
"id": "<string>",
"title": "<string>",
"missing": true
}
}
],
"checks": "<string>",
"body": "<string>",
"status": "active",
"kind": "browser",
"tools": [
"<string>"
],
"approval": {
"required": true,
"by": "anyone",
"who": "",
"covers": [],
"note": ""
},
"model": "claude-haiku-5-5",
"plan_mode": "off",
"plan": {
"mode": "off",
"status": "off",
"revision": 123,
"compiled_at": "2023-11-07T05:31:56Z",
"error": "<string>",
"steps_count": 123,
"vars": [
{
"name": "<string>",
"description": "<string>",
"list": true
}
],
"steps": [
{
"id": "<string>",
"kind": "ask",
"text": "<string>",
"inputs": [
"<string>"
],
"tool": "<string>",
"args": [
{
"name": "<string>",
"value": "<string>"
}
],
"options": [
{
"when": "<string>",
"next": "<string>"
}
],
"procedure": "<string>",
"next": "<string>",
"type": "open",
"url": "<string>",
"page": "<string>",
"keys": [
"<string>"
],
"target": {
"role": "<string>",
"label": "<string>"
},
"focus": {
"role": "<string>",
"label": "<string>"
}
}
],
"recorded_from": "<string>"
},
"category": "<string>",
"written_by": "person",
"source_task_id": "<string>",
"revision": 123,
"uses_30d": 123,
"last_used_at": "2023-11-07T05:31:56Z",
"avg_run_cents_30d": 123,
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"evals": {
"test_cases": 4,
"last_run": {
"test_run_id": "<string>",
"at": "2023-11-07T05:31:56Z",
"tries": 123,
"passed": 123,
"pass_rate": 123,
"found": 123,
"revision": 123,
"current": true
}
},
"references": [
{
"type": "tool",
"id": "<string>",
"name": "<string>",
"title": "<string>",
"missing": true
}
],
"file_access": "read_only",
"test_cases": [
{
"object": "test_case",
"test_case_id": "tc_8Kq2mZ0aLp4x",
"key": "DSP-01",
"name": "Apps switched to dark mode",
"prompt": "All my windows suddenly went black. How do I get the white back?",
"start_state": "win10-22h2",
"setup_script": "<string>",
"success": {
"check_script": "<string>",
"rubric": "<string>"
},
"customer": {
"persona": "Retired teacher. Not technical. Short, polite answers.",
"facts": {
"Wi-Fi network": "HomeNet",
"Wi-Fi password": {
"secret": "blue-kite-42"
}
},
"clicks_admin_prompts": true,
"does_steps": true
},
"operator": {
"approvals": "approve"
},
"limits": {
"minutes": 10,
"steps": 250
},
"runs_on": "vm",
"category": "Display & graphics",
"tags": [
"uac"
],
"metadata": {
"customer_id": "cus_42"
},
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"must_visit": [
"support.example.com|docs.example.com"
],
"expected": "<string>",
"messages": [
"<string>"
],
"start_url": "<string>",
"procedure_id": "prc_4mJx0aQe1",
"inputs": [
{
"mtm": "20XW",
"region": "UK"
},
{
"mtm": "21DE",
"region": "US"
}
],
"objects": [
"<string>"
]
}
]
}
],
"created": 123,
"updated": 123,
"unchanged": 123,
"test_cases": {
"created": 123,
"updated": 123
}
}{
"error": {
"type": "invalid_request",
"message": "<string>",
"code": "<string>",
"test_case_ids": [
"<string>"
],
"decided_by": {
"type": "person",
"email": "<string>",
"key_id": "<string>"
},
"conversation_id": "<string>",
"agent_id": "<string>",
"approval_id": "<string>",
"question_id": "<string>"
}
}{
"error": {
"type": "invalid_request",
"message": "<string>",
"code": "<string>",
"test_case_ids": [
"<string>"
],
"decided_by": {
"type": "person",
"email": "<string>",
"key_id": "<string>"
},
"conversation_id": "<string>",
"agent_id": "<string>",
"approval_id": "<string>",
"question_id": "<string>"
}
}{
"error": {
"type": "invalid_request",
"message": "<string>",
"code": "<string>",
"test_case_ids": [
"<string>"
],
"decided_by": {
"type": "person",
"email": "<string>",
"key_id": "<string>"
},
"conversation_id": "<string>",
"agent_id": "<string>",
"approval_id": "<string>",
"question_id": "<string>"
}
}Procedures
Add or change procedures
Makes and changes up to 50 procedures at once, each with the test cases that check it (up to 20 each, 500 in all). All of them are saved, or none: the first that can’t be saved says why (procedures[1]: …). With test_set_id, also adds every case to that test set. The body can be up to 8 MB. Needs the admin role or an API key.
POST
/
v1
/
agents
/
{agent_id}
/
procedures
/
batch
Add or change procedures
curl --request POST \
--url https://guidinghand.ai/v1/agents/{agent_id}/procedures/batch \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"procedures": [
{
"id": "<string>",
"revision": 123,
"title": "<string>",
"use_when": "<string>",
"inputs": [
{
"name": "<string>",
"type": "text",
"description": "<string>",
"required": true,
"options": [
"<string>"
],
"example": "<string>"
}
],
"goal": "<string>",
"context": "<string>",
"instructions": "<string>",
"steps": [
"<string>"
],
"checks": "<string>",
"body": "<string>",
"tools": [
"<string>"
],
"approval": {
"required": true,
"by": "anyone",
"who": "",
"covers": [],
"note": ""
},
"category": "<string>",
"test_cases": [
{
"name": "Apps switched to dark mode",
"prompt": "All my windows suddenly went black. How do I get the white back?",
"key": "DSP-01",
"start_state": "win10-22h2",
"setup_script": "<string>",
"success": {
"check_script": "<string>",
"rubric": "<string>"
},
"customer": {
"persona": "Retired teacher. Not technical. Short, polite answers.",
"facts": {
"Wi-Fi network": "HomeNet",
"Wi-Fi password": {
"secret": "blue-kite-42"
}
},
"clicks_admin_prompts": true,
"does_steps": true
},
"operator": {},
"limits": {
"minutes": 10,
"steps": 250
},
"runs_on": "vm",
"category": "Display & graphics",
"tags": [
"uac"
],
"metadata": {
"customer_id": "cus_42"
},
"must_visit": [
"support.example.com|docs.example.com"
],
"expected": "<string>",
"messages": [
"<string>"
],
"start_url": "<string>",
"procedure_id": "prc_4mJx0aQe1",
"inputs": [
{
"mtm": "20XW",
"region": "UK"
},
{
"mtm": "21DE",
"region": "US"
}
],
"objects": [
"<string>"
]
}
]
}
],
"test_set_id": "<string>"
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
procedures: [
{
id: '<string>',
revision: 123,
title: '<string>',
use_when: '<string>',
inputs: [
{
name: '<string>',
type: 'text',
description: '<string>',
required: true,
options: ['<string>'],
example: '<string>'
}
],
goal: '<string>',
context: '<string>',
instructions: '<string>',
steps: ['<string>'],
checks: '<string>',
body: JSON.stringify('<string>'),
tools: ['<string>'],
approval: {required: true, by: 'anyone', who: '', covers: [], note: ''},
category: '<string>',
test_cases: [
{
name: 'Apps switched to dark mode',
prompt: 'All my windows suddenly went black. How do I get the white back?',
key: 'DSP-01',
start_state: 'win10-22h2',
setup_script: '<string>',
success: {check_script: '<string>', rubric: '<string>'},
customer: {
persona: 'Retired teacher. Not technical. Short, polite answers.',
facts: {'Wi-Fi network': 'HomeNet', 'Wi-Fi password': {secret: 'blue-kite-42'}},
clicks_admin_prompts: true,
does_steps: true
},
operator: {},
limits: {minutes: 10, steps: 250},
runs_on: 'vm',
category: 'Display & graphics',
tags: ['uac'],
metadata: {customer_id: 'cus_42'},
must_visit: ['support.example.com|docs.example.com'],
expected: '<string>',
messages: ['<string>'],
start_url: '<string>',
procedure_id: 'prc_4mJx0aQe1',
inputs: [{mtm: '20XW', region: 'UK'}, {mtm: '21DE', region: 'US'}],
objects: ['<string>']
}
]
}
],
test_set_id: '<string>'
})
};
fetch('https://guidinghand.ai/v1/agents/{agent_id}/procedures/batch', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://guidinghand.ai/v1/agents/{agent_id}/procedures/batch"
payload = {
"procedures": [
{
"id": "<string>",
"revision": 123,
"title": "<string>",
"use_when": "<string>",
"inputs": [
{
"name": "<string>",
"type": "text",
"description": "<string>",
"required": True,
"options": ["<string>"],
"example": "<string>"
}
],
"goal": "<string>",
"context": "<string>",
"instructions": "<string>",
"steps": ["<string>"],
"checks": "<string>",
"body": "<string>",
"tools": ["<string>"],
"approval": {
"required": True,
"by": "anyone",
"who": "",
"covers": [],
"note": ""
},
"category": "<string>",
"test_cases": [
{
"name": "Apps switched to dark mode",
"prompt": "All my windows suddenly went black. How do I get the white back?",
"key": "DSP-01",
"start_state": "win10-22h2",
"setup_script": "<string>",
"success": {
"check_script": "<string>",
"rubric": "<string>"
},
"customer": {
"persona": "Retired teacher. Not technical. Short, polite answers.",
"facts": {
"Wi-Fi network": "HomeNet",
"Wi-Fi password": { "secret": "blue-kite-42" }
},
"clicks_admin_prompts": True,
"does_steps": True
},
"operator": {},
"limits": {
"minutes": 10,
"steps": 250
},
"runs_on": "vm",
"category": "Display & graphics",
"tags": ["uac"],
"metadata": { "customer_id": "cus_42" },
"must_visit": ["support.example.com|docs.example.com"],
"expected": "<string>",
"messages": ["<string>"],
"start_url": "<string>",
"procedure_id": "prc_4mJx0aQe1",
"inputs": [
{
"mtm": "20XW",
"region": "UK"
},
{
"mtm": "21DE",
"region": "US"
}
],
"objects": ["<string>"]
}
]
}
],
"test_set_id": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"object": "list",
"data": [
{
"object": "procedure",
"id": "prc_…",
"agent_id": "<string>",
"title": "<string>",
"use_when": "<string>",
"inputs": [
{
"name": "<string>",
"type": "text",
"description": "<string>",
"required": true,
"options": [
"<string>"
],
"example": "<string>"
}
],
"goal": "<string>",
"context": "<string>",
"instructions": "<string>",
"steps": [
{
"id": "<string>",
"text": "<string>",
"subprocedure": {
"id": "<string>",
"title": "<string>",
"missing": true
}
}
],
"checks": "<string>",
"body": "<string>",
"status": "active",
"kind": "browser",
"tools": [
"<string>"
],
"approval": {
"required": true,
"by": "anyone",
"who": "",
"covers": [],
"note": ""
},
"model": "claude-haiku-5-5",
"plan_mode": "off",
"plan": {
"mode": "off",
"status": "off",
"revision": 123,
"compiled_at": "2023-11-07T05:31:56Z",
"error": "<string>",
"steps_count": 123,
"vars": [
{
"name": "<string>",
"description": "<string>",
"list": true
}
],
"steps": [
{
"id": "<string>",
"kind": "ask",
"text": "<string>",
"inputs": [
"<string>"
],
"tool": "<string>",
"args": [
{
"name": "<string>",
"value": "<string>"
}
],
"options": [
{
"when": "<string>",
"next": "<string>"
}
],
"procedure": "<string>",
"next": "<string>",
"type": "open",
"url": "<string>",
"page": "<string>",
"keys": [
"<string>"
],
"target": {
"role": "<string>",
"label": "<string>"
},
"focus": {
"role": "<string>",
"label": "<string>"
}
}
],
"recorded_from": "<string>"
},
"category": "<string>",
"written_by": "person",
"source_task_id": "<string>",
"revision": 123,
"uses_30d": 123,
"last_used_at": "2023-11-07T05:31:56Z",
"avg_run_cents_30d": 123,
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"evals": {
"test_cases": 4,
"last_run": {
"test_run_id": "<string>",
"at": "2023-11-07T05:31:56Z",
"tries": 123,
"passed": 123,
"pass_rate": 123,
"found": 123,
"revision": 123,
"current": true
}
},
"references": [
{
"type": "tool",
"id": "<string>",
"name": "<string>",
"title": "<string>",
"missing": true
}
],
"file_access": "read_only",
"test_cases": [
{
"object": "test_case",
"test_case_id": "tc_8Kq2mZ0aLp4x",
"key": "DSP-01",
"name": "Apps switched to dark mode",
"prompt": "All my windows suddenly went black. How do I get the white back?",
"start_state": "win10-22h2",
"setup_script": "<string>",
"success": {
"check_script": "<string>",
"rubric": "<string>"
},
"customer": {
"persona": "Retired teacher. Not technical. Short, polite answers.",
"facts": {
"Wi-Fi network": "HomeNet",
"Wi-Fi password": {
"secret": "blue-kite-42"
}
},
"clicks_admin_prompts": true,
"does_steps": true
},
"operator": {
"approvals": "approve"
},
"limits": {
"minutes": 10,
"steps": 250
},
"runs_on": "vm",
"category": "Display & graphics",
"tags": [
"uac"
],
"metadata": {
"customer_id": "cus_42"
},
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"must_visit": [
"support.example.com|docs.example.com"
],
"expected": "<string>",
"messages": [
"<string>"
],
"start_url": "<string>",
"procedure_id": "prc_4mJx0aQe1",
"inputs": [
{
"mtm": "20XW",
"region": "UK"
},
{
"mtm": "21DE",
"region": "US"
}
],
"objects": [
"<string>"
]
}
]
}
],
"created": 123,
"updated": 123,
"unchanged": 123,
"test_cases": {
"created": 123,
"updated": 123
}
}{
"error": {
"type": "invalid_request",
"message": "<string>",
"code": "<string>",
"test_case_ids": [
"<string>"
],
"decided_by": {
"type": "person",
"email": "<string>",
"key_id": "<string>"
},
"conversation_id": "<string>",
"agent_id": "<string>",
"approval_id": "<string>",
"question_id": "<string>"
}
}{
"error": {
"type": "invalid_request",
"message": "<string>",
"code": "<string>",
"test_case_ids": [
"<string>"
],
"decided_by": {
"type": "person",
"email": "<string>",
"key_id": "<string>"
},
"conversation_id": "<string>",
"agent_id": "<string>",
"approval_id": "<string>",
"question_id": "<string>"
}
}{
"error": {
"type": "invalid_request",
"message": "<string>",
"code": "<string>",
"test_case_ids": [
"<string>"
],
"decided_by": {
"type": "person",
"email": "<string>",
"key_id": "<string>"
},
"conversation_id": "<string>",
"agent_id": "<string>",
"approval_id": "<string>",
"question_id": "<string>"
}
}Authorizations
An org API key (gh_live_…) from Settings → API keys in the console.
Path Parameters
The agent’s id.
Body
application/json
Response
OK