curl --request POST \
--url https://guidinghand.ai/v1/conversations/{conversation_id}/decisions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{}'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({})
};
fetch('https://guidinghand.ai/v1/conversations/{conversation_id}/decisions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://guidinghand.ai/v1/conversations/{conversation_id}/decisions"
payload = {}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"object": "decision",
"approval": {
"approval_id": "apr_…",
"scope": "run",
"action": "<string>",
"source": "guardrail",
"site": "<string>",
"app": "<string>",
"category": "<string>",
"risk": "<string>",
"task_id": "<string>",
"procedure_id": "<string>",
"by": "anyone",
"who": "<string>",
"note": "<string>",
"covers": [
"purchase"
],
"surface_id": "<string>",
"a2ui": [
{}
],
"decision": {
"decision": "approve",
"note": "<string>",
"by": {
"type": "person",
"email": "<string>",
"key_id": "<string>"
},
"at": "2023-11-07T05:31:56Z"
}
},
"question": {
"question_id": "qst_…",
"task_id": "<string>",
"question": "<string>",
"options": [
"<string>"
],
"surface_id": "<string>",
"a2ui": [
{}
],
"answer": {
"text": "<string>",
"by": {
"type": "person",
"email": "<string>",
"key_id": "<string>"
},
"at": "2023-11-07T05:31:56Z"
}
}
}{
"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>"
}
}{
"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>"
}
}Decide a request
Approves or denies one of the conversation’s approval items, or answers a question item, as your team (the API key, or the member signed in). Send exactly one of approval, answer or action. No agent is named, so it works in any conversation, including the one a task run without an agent gets. The decision reaches the task waiting on it, and a reply paused for it (requires_action) carries on by itself: follow it with GET /v1/responses/, or decide with POST /v1/agents//responses to stream it instead. Answers at once, with the request as decided. 409 with code: already_decided and decided_by when someone decided first, or not_pending when its task has ended, so nothing would act on it.
curl --request POST \
--url https://guidinghand.ai/v1/conversations/{conversation_id}/decisions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{}'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({})
};
fetch('https://guidinghand.ai/v1/conversations/{conversation_id}/decisions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://guidinghand.ai/v1/conversations/{conversation_id}/decisions"
payload = {}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"object": "decision",
"approval": {
"approval_id": "apr_…",
"scope": "run",
"action": "<string>",
"source": "guardrail",
"site": "<string>",
"app": "<string>",
"category": "<string>",
"risk": "<string>",
"task_id": "<string>",
"procedure_id": "<string>",
"by": "anyone",
"who": "<string>",
"note": "<string>",
"covers": [
"purchase"
],
"surface_id": "<string>",
"a2ui": [
{}
],
"decision": {
"decision": "approve",
"note": "<string>",
"by": {
"type": "person",
"email": "<string>",
"key_id": "<string>"
},
"at": "2023-11-07T05:31:56Z"
}
},
"question": {
"question_id": "qst_…",
"task_id": "<string>",
"question": "<string>",
"options": [
"<string>"
],
"surface_id": "<string>",
"a2ui": [
{}
],
"answer": {
"text": "<string>",
"by": {
"type": "person",
"email": "<string>",
"key_id": "<string>"
},
"at": "2023-11-07T05:31:56Z"
}
}
}{
"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>"
}
}{
"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 conversation’s id.
Body
Exactly one of approval, answer or action.
Approves or denies an approval item of the conversation (its approval_id).
Show child attributes
Show child attributes
Answers a question item of the conversation (its question_id).
Show child attributes
Show child attributes
An A2UI action on a request’s surface (the item’s surface_id), as a renderer sends it (or wrapped as { version: "v0.9", action }): on an approval item’s, name is approve or deny (and context.note, if any, the note); on a question item’s, its form’s submit (context: { answer: ["<option>"] }, or { answer: "<text>" } with no options).
Show child attributes
Show child attributes
Response
The request, decided.
A request decided (POST /v1/conversations/{conversation_id}/decisions, or the responses route when no reply was paused for it): the approval or question as it is now.
A request for a yes before something runs: a task from a procedure whose Approval is on (scope: run), an HTTP tool with approval: "always", or one guarded step of a task (scope: step). Described by Eager, never by the model. Open while decision is null; the first decision counts.
Show child attributes
Show child attributes
A question a task asks, drawn as a form: a choice from options (or something else), or short text. Open while answer is null; the first answer counts.
Show child attributes
Show child attributes