wait

GET

/v1/requests/{id}/wait

const url = 'https://example.com/v1/requests/example/wait';
const options = {method: 'GET'};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://example.com/v1/requests/example/wait

Parameters

Path Parameters

required

string

Query Parameters

timeout

string

Long poll duration, default 25s, maximum 60s

Responses

200

application/json

object

string

title

required

string

tool

string | null

callback_url

Terminal-event destination; requires the daemon callbacks.allowlist.

string | null

summary

string | null

source

object

integration

Server-verified integration token name; caller values are overwritten.

string | null

agent

string | null

session

string | null

session_title

Display-only session name; scoped rules always use the session ID.

string | null

cwd

string | null

repo

string | null

branch

string | null

host

string | null

kind

string

Allowed values: command edit review question custom

risk

string

Allowed values: low medium high

previews

Array<object>

object

type

required

string

Allowed values: text markdown code diff files command json html image video audio file pdf email

title

string | null

lang

string | null

inline

string | null

blob

string | null

mime

string | null

name

string | null

size

integer | null format: int64

files

Array<object> | null

object

path

required

string

blob

required

string

mime

required

string

size

required

integer format: int64

lang

string | null

entry

string | null

command

One of:

null
object

null

email

One of:

null
object

null

An email draft for review. handup never sends it: on approval the agent sends the draft (or the edited decision.fields) with its own mail tool.

object

from

string | null

Array<string>

default:

Array<string>

default:

bcc

Array<string>

default:

reply_to

string | null

subject

string

date

Date shown in the header, as the agent formats it (e.g. RFC 2822).

string | null

body

Message body as Markdown (plain text renders as-is).

string

body_html

Optional HTML alternative; rendered only in the sandboxed HTML preview frame.

string | null

attachments

Array<object>

default:

object

name

required

string

mime

string | null

size

integer | null format: int64

blob

Uploaded blob hash (POST /v1/blobs) so the reviewer can open the file.

string | null

in_reply_to

One of:

null
object

null

before_blob

string | null

after_blob

string | null

options

Array<object>

object

required

string

label

required

string

outcome

required

string

Allowed values: approve deny

style

string | null

input

One of:

null
object

null

Request input. Only kind: question requests interpret questions; other keys (for example raw agent tool input) pass through unchanged.

object

feedback

optional (default) or required_on_deny.

string | null

fields

Generic form fields (text, textarea, select, boolean) for non-question requests.

Array | null

questions

Structured questions (1..=10) for kind: question; answers arrive in decision.fields.answers.

Array<object> | null

A question for the human; answered in decision.fields.answers[id].

object

required

Stable id, unique within the request.

string

header

Short topic chip, e.g. “Database”.

string | null

question

required

The question itself (markdown).

string

multi

Allow selecting several options.

boolean

recommended

Index of the suggested option.

integer | null

allow_free_text

Allow a typed answer besides (or instead of) the options.

boolean

options

Array<object>

One selectable answer to a [Question].

object

label

required

Answer text; unique within its question and returned in selected.

string

description

One-line explanation shown under the label.

string | null

preview

Markdown shown while the option is focused (code blocks allowed).

string | null

timeout

Optional positive duration, at most one year. Absent uses config; null/none disables expiry.

string | null

on_timeout

string

Allowed values: deny approve expire

dedupe_key

string | null

status

string

Allowed values: pending approved denied answered expired cancelled

content_hash

string

created_at

integer format: int64

expires_at

integer | null format: int64

decision

One of:

null
object

null

object

option

required

string

feedback

string | null

fields

One of:

null
object

null

Decision fields. Question requests carry only answers, keyed by question id; other requests carry answers to input.fields or edited tool input.

object

answers

object | null

content_hash

required

string

decided_by

string | null

decided_at

integer | null format: int64

outcome

One of:

null
string

null

rule_id

string | null

scope

string | null

run_result

One of:

null
object

null

run

One of:

null
object

null

Example

{
  "source": {
    "integration": null,
    "agent": null,
    "session": null,
    "session_title": null,
    "cwd": null,
    "repo": null,
    "branch": null,
    "host": null
  },
  "kind": "command",
  "risk": "low",
  "previews": [
    {
      "type": "text",
      "command": {
        "shell": null,
        "argv": null,
        "cwd": null,
        "env_keys": []
      },
      "email": {
        "from": null,
        "to": [],
        "cc": [],
        "bcc": [],
        "reply_to": null,
        "subject": "",
        "date": null,
        "body": "",
        "body_html": null,
        "attachments": [],
        "in_reply_to": null
      }
    }
  ],
  "options": [
    {
      "outcome": "approve"
    }
  ],
  "on_timeout": "deny",
  "status": "pending",
  "decision": {
    "outcome": "approve"
  }
}