cancel

POST

/v1/requests/{id}/cancel

curl --request POST \
  --url https://example.com/v1/requests/example/cancel

Parameters

Path Parameters

id

required

string

Responses

200

Media typeapplication/json

object

id

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

null

object

object

shell

string | null

argv

Array<string> | null

cwd

string | null

env_keys

Array<string>

default:

email

One of:

null

null

object

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

to

Array<string>

default:

cc

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

null

object

The message this draft replies to, shown collapsed under the body.

object

from

string | null

date

string | null

body

Plain text of the earlier message (or a snippet of it).

string

""

before_blob

string | null

after_blob

string | null

options

Array<object>

object

id

required

string

label

required

string

outcome

required

string

Allowed values: approve deny

style

string | null

input

One of:

null

null

object

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

id

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

null

object

object

option

required

string

feedback

string | null

fields

One of:

null

null

object

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

null

string

string

Allowed values: approve deny

rule_id

string | null

scope

string | null

run_result

One of:

null

null

object

The desktop app ran the request’s command for the human: this is how it ended. Present only on approved command requests decided by Run.

object

exit_code

Process exit status; absent when it never started or a signal ended it.

integer | null format: int32

stdout_tail

Last bytes of standard output (at most 64 KiB), credentials redacted.

string

stderr_tail

Last bytes of standard error (at most 64 KiB), credentials redacted.

string

duration_ms

Wall time from start to exit, in milliseconds.

integer format: int64

truncated

Earlier output was dropped from either tail.

boolean

elevated

Ran with administrator rights (pkexec on Linux, osascript on macOS).

boolean

error

Why it did not finish normally: timeout, cancellation, signal, or a start failure (for example pkexec missing or authentication refused).

string | null

run

One of:

null

null

object

Present while the desktop app runs the command (daemon-managed).

object

started_at

required

Unix milliseconds when the run was claimed.

integer format: int64

lease_until

required

Unix milliseconds after which an unreported run no longer holds the request (the app crashed or lost the daemon).

integer format: int64

elevated

Running with administrator rights.

boolean

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"
  }
}

409

Not pending