curl --request POST \
--url https://guidinghand.ai/v1/agents/{agent_id}/responses \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"input": "<string>",
"conversation_id": "<string>",
"opening": "<string>",
"variables": {},
"stream": true,
"version": "draft",
"metadata": {},
"attachments": [
"<string>"
]
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
input: '<string>',
conversation_id: '<string>',
opening: '<string>',
variables: {},
stream: true,
version: 'draft',
metadata: {},
attachments: ['<string>']
})
};
fetch('https://guidinghand.ai/v1/agents/{agent_id}/responses', 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}/responses"
payload = {
"input": "<string>",
"conversation_id": "<string>",
"opening": "<string>",
"variables": {},
"stream": True,
"version": "draft",
"metadata": {},
"attachments": ["<string>"]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"object": "response",
"id": "resp_…",
"conversation_id": "<string>",
"status": "in_progress",
"error": "<string>",
"output": [
{
"object": "conversation_item",
"seq": 123,
"response_id": "<string>",
"at": "2023-11-07T05:31:56Z",
"type": "user_message",
"text": "<string>",
"speaker": "caller",
"queued": true,
"view": {
"version": 1,
"sections": [
{
"blocks": [
{
"type": "text"
}
],
"title": "<string>",
"badge": {
"text": "<string>",
"tone": "neutral"
}
}
]
},
"call_id": "<string>",
"name": "<string>",
"arguments": {},
"label": "<string>",
"output": "<string>",
"task": {
"task_id": "<string>",
"kind": "browser",
"status": "queued",
"result": "<string>",
"goal": "<string>",
"computer": "<string>",
"plan": [
"<string>"
],
"plan_step": 2
},
"files": [
{
"id": "<string>",
"filename": "<string>",
"content_type": "<string>",
"kind": "image",
"bytes": 123
}
],
"error": true,
"surface_id": "<string>",
"title": "<string>",
"fields": [
{}
],
"a2ui": [
{}
],
"answer": {},
"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"
}
}
}
],
"usage": {
"input_tokens": 123,
"cached_tokens": 123,
"cache_write_tokens": 123,
"output_tokens": 123,
"reasoning_tokens": 123,
"tasks": [
{
"task_id": "<string>",
"cost_cents": 123
}
],
"code_runs": 123
},
"created_at": "2023-11-07T05:31:56Z",
"ended_at": "2023-11-07T05:31:56Z",
"queued_message": {
"object": "conversation_item",
"seq": 123,
"response_id": "<string>",
"at": "2023-11-07T05:31:56Z",
"type": "user_message",
"text": "<string>",
"speaker": "caller",
"queued": true,
"view": {
"version": 1,
"sections": [
{
"blocks": [
{
"type": "text"
}
],
"title": "<string>",
"badge": {
"text": "<string>",
"tone": "neutral"
}
}
]
},
"call_id": "<string>",
"name": "<string>",
"arguments": {},
"label": "<string>",
"output": "<string>",
"task": {
"task_id": "<string>",
"kind": "browser",
"status": "queued",
"result": "<string>",
"goal": "<string>",
"computer": "<string>",
"plan": [
"<string>"
],
"plan_step": 2
},
"files": [
{
"id": "<string>",
"filename": "<string>",
"content_type": "<string>",
"kind": "image",
"bytes": 123
}
],
"error": true,
"surface_id": "<string>",
"title": "<string>",
"fields": [
{}
],
"a2ui": [
{}
],
"answer": {},
"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"
}
}
}
}{
"object": "response",
"id": "resp_…",
"conversation_id": "<string>",
"status": "in_progress",
"error": "<string>",
"output": [
{
"object": "conversation_item",
"seq": 123,
"response_id": "<string>",
"at": "2023-11-07T05:31:56Z",
"type": "user_message",
"text": "<string>",
"speaker": "caller",
"queued": true,
"view": {
"version": 1,
"sections": [
{
"blocks": [
{
"type": "text"
}
],
"title": "<string>",
"badge": {
"text": "<string>",
"tone": "neutral"
}
}
]
},
"call_id": "<string>",
"name": "<string>",
"arguments": {},
"label": "<string>",
"output": "<string>",
"task": {
"task_id": "<string>",
"kind": "browser",
"status": "queued",
"result": "<string>",
"goal": "<string>",
"computer": "<string>",
"plan": [
"<string>"
],
"plan_step": 2
},
"files": [
{
"id": "<string>",
"filename": "<string>",
"content_type": "<string>",
"kind": "image",
"bytes": 123
}
],
"error": true,
"surface_id": "<string>",
"title": "<string>",
"fields": [
{}
],
"a2ui": [
{}
],
"answer": {},
"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"
}
}
}
],
"usage": {
"input_tokens": 123,
"cached_tokens": 123,
"cache_write_tokens": 123,
"output_tokens": 123,
"reasoning_tokens": 123,
"tasks": [
{
"task_id": "<string>",
"cost_cents": 123
}
],
"code_runs": 123
},
"created_at": "2023-11-07T05:31:56Z",
"ended_at": "2023-11-07T05:31:56Z",
"queued_message": {
"object": "conversation_item",
"seq": 123,
"response_id": "<string>",
"at": "2023-11-07T05:31:56Z",
"type": "user_message",
"text": "<string>",
"speaker": "caller",
"queued": true,
"view": {
"version": 1,
"sections": [
{
"blocks": [
{
"type": "text"
}
],
"title": "<string>",
"badge": {
"text": "<string>",
"tone": "neutral"
}
}
]
},
"call_id": "<string>",
"name": "<string>",
"arguments": {},
"label": "<string>",
"output": "<string>",
"task": {
"task_id": "<string>",
"kind": "browser",
"status": "queued",
"result": "<string>",
"goal": "<string>",
"computer": "<string>",
"plan": [
"<string>"
],
"plan_step": 2
},
"files": [
{
"id": "<string>",
"filename": "<string>",
"content_type": "<string>",
"kind": "image",
"bytes": 123
}
],
"error": true,
"surface_id": "<string>",
"title": "<string>",
"fields": [
{}
],
"a2ui": [
{}
],
"answer": {},
"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>"
}
}{
"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>"
}
}Send a message to an agent
One turn: the agent reads input (and any attachments) and answers, using its tools, showing a form when it needs details, and running browser tasks (on the conversation’s cloud browser) or desktop tasks (on its linked computers) when it needs a website or a desktop app. Without conversation_id a new conversation starts. Waits up to 55 seconds; a turn still running then comes back in_progress (poll GET /v1/responses/). With stream: true the answer is server-sent events: response.created; output_text.delta (text: the next piece of the reply as the model writes it; output_text.reset takes back what a failed try streamed); message.delta (each whole message once written); tool_call.started, tool_call.completed (a code run’s has files: what the code made); ui (a form: surface_id, title, fields, a2ui; the turn ends after it); task.started (task_id, goal, kind: browser or desktop, computer for a desktop task, plan: the steps the person sees as its progress, the browser’s session_id, and live_url: its live view in the console), task.step (text: what it says it’s doing now, and with a plan plan_step: the step it’s on), task.completed; input.delivered (messages sent meanwhile, read); with visual answers on, answer.layout first (its answer may be laid out as UI) and message.view (seq, view: that answer laid out as cards, before the reply ends; its text is still the answer); then response.completed, response.failed, response.cancelled, or response.requires_action (response: the reply, paused on a request in its output). A message sent while a reply is still running is queued for that reply instead: 202 at once (streamed or not), with the reply as it is now and queued_message (your message’s item, queued: true). The reply reads it at its next step, after the tool or task it’s running (a task it’s running reads it at its next step too), or carries on after its answer to answer it as well, so the one reply answers both: follow it on its own stream or with GET /v1/responses/. Its stream has input.delivered (seqs: the items read, to: reply or task) when it reads them. A reply cancelled or failed before it read one leaves it in the conversation for the next turn. A failed turn still answers 200, with status: failed. If a deploy hands a streamed turn to another server, the stream can close without a response.* event: follow it with GET /v1/responses/. A reply that reaches something needing approval (a procedure whose Approval is on, an HTTP tool with approval: "always", or a step one of its tasks hands back: the task is paused until it’s decided, then carries on) pauses: status: requires_action, with the request (an approval item) in output. Decide it with conversation_id and approval (or an A2UI action on its surface), and no input; a question is answered the same way with answer. Your team decides, as the API key or the member signed in. The same reply carries on (same id), streamed with stream: true; it still waits while another request is open. With no paused reply (a task started directly) the answer is the decision: { object: "decision", approval | question }. To decide without naming an agent (a task run without one) or streaming, use POST /v1/conversations//decisions. Someone deciding first: 409 with code: already_decided and decided_by.
curl --request POST \
--url https://guidinghand.ai/v1/agents/{agent_id}/responses \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"input": "<string>",
"conversation_id": "<string>",
"opening": "<string>",
"variables": {},
"stream": true,
"version": "draft",
"metadata": {},
"attachments": [
"<string>"
]
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
input: '<string>',
conversation_id: '<string>',
opening: '<string>',
variables: {},
stream: true,
version: 'draft',
metadata: {},
attachments: ['<string>']
})
};
fetch('https://guidinghand.ai/v1/agents/{agent_id}/responses', 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}/responses"
payload = {
"input": "<string>",
"conversation_id": "<string>",
"opening": "<string>",
"variables": {},
"stream": True,
"version": "draft",
"metadata": {},
"attachments": ["<string>"]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"object": "response",
"id": "resp_…",
"conversation_id": "<string>",
"status": "in_progress",
"error": "<string>",
"output": [
{
"object": "conversation_item",
"seq": 123,
"response_id": "<string>",
"at": "2023-11-07T05:31:56Z",
"type": "user_message",
"text": "<string>",
"speaker": "caller",
"queued": true,
"view": {
"version": 1,
"sections": [
{
"blocks": [
{
"type": "text"
}
],
"title": "<string>",
"badge": {
"text": "<string>",
"tone": "neutral"
}
}
]
},
"call_id": "<string>",
"name": "<string>",
"arguments": {},
"label": "<string>",
"output": "<string>",
"task": {
"task_id": "<string>",
"kind": "browser",
"status": "queued",
"result": "<string>",
"goal": "<string>",
"computer": "<string>",
"plan": [
"<string>"
],
"plan_step": 2
},
"files": [
{
"id": "<string>",
"filename": "<string>",
"content_type": "<string>",
"kind": "image",
"bytes": 123
}
],
"error": true,
"surface_id": "<string>",
"title": "<string>",
"fields": [
{}
],
"a2ui": [
{}
],
"answer": {},
"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"
}
}
}
],
"usage": {
"input_tokens": 123,
"cached_tokens": 123,
"cache_write_tokens": 123,
"output_tokens": 123,
"reasoning_tokens": 123,
"tasks": [
{
"task_id": "<string>",
"cost_cents": 123
}
],
"code_runs": 123
},
"created_at": "2023-11-07T05:31:56Z",
"ended_at": "2023-11-07T05:31:56Z",
"queued_message": {
"object": "conversation_item",
"seq": 123,
"response_id": "<string>",
"at": "2023-11-07T05:31:56Z",
"type": "user_message",
"text": "<string>",
"speaker": "caller",
"queued": true,
"view": {
"version": 1,
"sections": [
{
"blocks": [
{
"type": "text"
}
],
"title": "<string>",
"badge": {
"text": "<string>",
"tone": "neutral"
}
}
]
},
"call_id": "<string>",
"name": "<string>",
"arguments": {},
"label": "<string>",
"output": "<string>",
"task": {
"task_id": "<string>",
"kind": "browser",
"status": "queued",
"result": "<string>",
"goal": "<string>",
"computer": "<string>",
"plan": [
"<string>"
],
"plan_step": 2
},
"files": [
{
"id": "<string>",
"filename": "<string>",
"content_type": "<string>",
"kind": "image",
"bytes": 123
}
],
"error": true,
"surface_id": "<string>",
"title": "<string>",
"fields": [
{}
],
"a2ui": [
{}
],
"answer": {},
"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"
}
}
}
}{
"object": "response",
"id": "resp_…",
"conversation_id": "<string>",
"status": "in_progress",
"error": "<string>",
"output": [
{
"object": "conversation_item",
"seq": 123,
"response_id": "<string>",
"at": "2023-11-07T05:31:56Z",
"type": "user_message",
"text": "<string>",
"speaker": "caller",
"queued": true,
"view": {
"version": 1,
"sections": [
{
"blocks": [
{
"type": "text"
}
],
"title": "<string>",
"badge": {
"text": "<string>",
"tone": "neutral"
}
}
]
},
"call_id": "<string>",
"name": "<string>",
"arguments": {},
"label": "<string>",
"output": "<string>",
"task": {
"task_id": "<string>",
"kind": "browser",
"status": "queued",
"result": "<string>",
"goal": "<string>",
"computer": "<string>",
"plan": [
"<string>"
],
"plan_step": 2
},
"files": [
{
"id": "<string>",
"filename": "<string>",
"content_type": "<string>",
"kind": "image",
"bytes": 123
}
],
"error": true,
"surface_id": "<string>",
"title": "<string>",
"fields": [
{}
],
"a2ui": [
{}
],
"answer": {},
"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"
}
}
}
],
"usage": {
"input_tokens": 123,
"cached_tokens": 123,
"cache_write_tokens": 123,
"output_tokens": 123,
"reasoning_tokens": 123,
"tasks": [
{
"task_id": "<string>",
"cost_cents": 123
}
],
"code_runs": 123
},
"created_at": "2023-11-07T05:31:56Z",
"ended_at": "2023-11-07T05:31:56Z",
"queued_message": {
"object": "conversation_item",
"seq": 123,
"response_id": "<string>",
"at": "2023-11-07T05:31:56Z",
"type": "user_message",
"text": "<string>",
"speaker": "caller",
"queued": true,
"view": {
"version": 1,
"sections": [
{
"blocks": [
{
"type": "text"
}
],
"title": "<string>",
"badge": {
"text": "<string>",
"tone": "neutral"
}
}
]
},
"call_id": "<string>",
"name": "<string>",
"arguments": {},
"label": "<string>",
"output": "<string>",
"task": {
"task_id": "<string>",
"kind": "browser",
"status": "queued",
"result": "<string>",
"goal": "<string>",
"computer": "<string>",
"plan": [
"<string>"
],
"plan_step": 2
},
"files": [
{
"id": "<string>",
"filename": "<string>",
"content_type": "<string>",
"kind": "image",
"bytes": 123
}
],
"error": true,
"surface_id": "<string>",
"title": "<string>",
"fields": [
{}
],
"a2ui": [
{}
],
"answer": {},
"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>"
}
}{
"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, e.g. billing.
Body
What the person says, up to 8,000 characters. Can be empty when the message has attachments or answers a form (action), and is left out with a decision (approval, answer).
8000For a new conversation (no conversation_id), the agent's first message, shown as said before the person wrote and recorded as the agent's. Used only when the agent has no first message of its own.
500For a new conversation (no conversation_id): what it starts knowing, like { "customer_name": "Ana", "account_id": "A-77" }. Names are lowercase letters, numbers and _ (up to 40), values text up to 1,000 characters. The agent reads them with Eager's own (current_date, current_time, day_of_week, time_zone, language, channel, conversation_id, agent_name, and where known caller_number, agent_number, page_url, user_name, user_email) and doesn't ask for them; a procedure's input of the same name is taken as given. Eager's own names can't be passed, except time_zone (an IANA zone; the date and time are where the person is) and language. Sent with a conversation_id, it's a 400.
Show child attributes
Show child attributes
draft, or a version number, for this turn only. Default: the published version.
Your own values for a new conversation (a JSON object, up to 4,000 characters). Only used when the conversation is created.
Files the person attached: upload ids (upl_…) from POST /v1/uploads, up to 10. Images and PDFs the model sees, text files it reads; any other file needs Run code (tools.code, Claude or GPT models). A file sent in one conversation can’t be sent in another.
10Answers a form the agent showed (a ui item): { name: "submit", surfaceId, context: { <field id>: value } }, or the same wrapped as { version: "v0.9", action }. Needs conversation_id. The answers reach the agent as the person’s message; input, if sent too, is added after them. 404 for an unknown form, 409 if it was answered already. Or decides a request, as approval and answer do: on an approval item’s surface (surface_id), name is approve or deny; on a question item’s, its form’s submit (context: { answer: ["<option>"] }, or { answer: "<text>" } with no options).
Show child attributes
Show child attributes
Decides an approval item of the conversation (its approval_id): needs conversation_id, and no input. The reply that paused for it carries on.
Show child attributes
Show child attributes
Answers a question item of the conversation (its question_id): needs conversation_id, and no input.
Show child attributes
Show child attributes
Response
The turn (or, streamed, its events). A decision: the reply it carries on, or with no paused reply, the decision.
- Option 1
- Option 2
"resp_…"
requires_action: paused on a request in output (an approval or question item) until someone decides it. Send the decision to POST /v1/agents/{agent_id}/responses (approval, answer, or an A2UI action on its surface), and this same response carries on.
in_progress, requires_action, completed, failed, cancelled This turn’s items.
Show child attributes
Show child attributes
What the reply used, set when it ends (empty until then). Its tokens are paid from the balance at the model’s price, rounded up to a whole cent per reply. The browser and desktop tasks it started are charged as tasks.
Show child attributes
Show child attributes
Only when your message was queued (202): its item.
Show child attributes
Show child attributes